Geomap Widget

The geomap widget visualizes geographic data with shaded regions or points. It can be used to:

  • View user sessions by country.
  • Filter to see a list of all sessions in a new tab.
  • View user sessions filtered by employee.
  • Monitor performance metrics like load time, core web vitals, and percent of views with errors.
Geomap visualization with the points overlay

Setup

Geomap Graph your data section of widget configuration

Configuration

  1. Choose the visualization layer:

    • Regions: Aggregate measures at a country level.
    • Points: Overlay events as points on the map to display geographic event data.

  2. Choose the data to graph:
    Note: Support for data sources varies based on the visualization layer you select.

      Data sourceNotes
      Log EventsThe group by tag must include a country ISO Code following the alpha-2 ISO format. You can use the GeoIP Processor to do this, or manually include the tags on ingest. See the Log search documentation to configure a log event query.
      MetricThe group by tag must include a country ISO Code following the alpha-2 ISO format. You can generate metrics from ingested logs, or manually include the tags on ingest. See the querying documentation to configure a metric query.
      RUMSee the RUM documentation to configure a RUM query.
      SLOSee the SLO search documentation to configure an SLO query.
      Security Signals
      Application Security
      Audit Trail      		See the Log search documentation to configure a query.
      Data sourceNotes
      Log EventsThe group by tag must include a country ISO Code following the alpha-2 ISO format. You can use the GeoIP Processor to do this, or manually include the tags on ingest. See the Log search documentation to configure a log event query.
      RUMSee the RUM documentation to configure a RUM query.

    • Optional: Configure your view box to specify where you want to focus the map initially.

    Options

    Context links are enabled by default, you can toggle them on or off. Context links connect dashboard widgets with other pages (in Datadog, or third-party).

    API

    This widget can be used with the Dashboards API. See the following table for the widget JSON schema definition:

    Expand All

    Field

    Type

    Description

    custom_links

    [object]

    A list of custom links.

    is_hidden

    boolean

    The flag for toggling context menu link visibility.

    label

    string

    The label for the custom link URL. Keep the label short and descriptive. Use metrics and tags as variables.

    link

    string

    The URL of the custom link. URL must include http or https. A relative URL must start with /.

    override_label

    string

    The label ID that refers to a context menu link. Can be logs, hosts, traces, profiles, processes, containers, or rum.

    requests [required]

    [object]

    Array of one request object to display in the widget. The request must contain a group-by tag whose value is a country ISO code.

    See the Request JSON schema documentation for information about building the REQUEST_SCHEMA.

    columns

    [object]

    Widget columns.

    field [required]

    string

    Widget column field.

    is_clustering_pattern_field_path

    boolean

    Identifies the clustering pattern field column, usable only with logs_pattern_stream.

    width [required]

    enum

    Widget column width. Allowed enum values: auto,compact,full

    formulas

    [object]

    List of formulas that operate on queries.

    alias

    string

    Expression alias.

    cell_display_mode

    enum

    Define a display mode for the table cell. Allowed enum values: number,bar

    conditional_formats

    [object]

    List of conditional formats.

    comparator [required]

    enum

    Comparator to apply. Allowed enum values: =,>,>=,<,<=

    custom_bg_color

    string

    Color palette to apply to the background, same values available as palette.

    custom_fg_color

    string

    Color palette to apply to the foreground, same values available as palette.

    hide_value

    boolean

    True hides values.

    image_url

    string

    Displays an image as the background.

    metric

    string

    Metric from the request to correlate this conditional format with.

    palette [required]

    enum

    Color palette to apply. Allowed enum values: blue,custom_bg,custom_image,custom_text,gray_on_white,grey,green,orange,red,red_on_white,white_on_gray,white_on_green,green_on_white,white_on_red,white_on_yellow,yellow_on_white,black_on_light_yellow,black_on_light_green,black_on_light_red

    timeframe

    string

    Defines the displayed timeframe.

    value [required]

    double

    Value for the comparator.

    formula [required]

    string

    String expression built from queries, formulas, and functions.

    limit

    object

    Options for limiting results returned.

    count

    int64

    Number of results to return.

    order

    enum

    Direction of sort. Allowed enum values: asc,desc

    default: desc

    style

    object

    Styling options for widget formulas.

    palette

    string

    The color palette used to display the formula. A guide to the available color palettes can be found at https://docs.datadoghq.com/dashboards/guide/widget_colors

    palette_index

    int64

    Index specifying which color to use within the palette.

    log_query

    object

    The log query.

    compute

    object

    Define computation for a log query.

    aggregation [required]

    string

    The aggregation method.

    facet

    string

    Facet name.

    interval

    int64

    Define a time interval in seconds.

    group_by

    [object]

    List of tag prefixes to group by in the case of a cluster check.

    facet [required]

    string

    Facet name.

    limit

    int64

    Maximum number of items in the group.

    sort

    object

    Define a sorting method.

    aggregation [required]

    string

    The aggregation method.

    facet

    string

    Facet name.

    order [required]

    enum

    Widget sorting methods. Allowed enum values: asc,desc

    index

    string

    A coma separated-list of index names. Use "*" query all indexes at once. Multiple Indexes

    multi_compute

    [object]

    This field is mutually exclusive with compute.

    aggregation [required]

    string

    The aggregation method.

    facet

    string

    Facet name.

    interval

    int64

    Define a time interval in seconds.

    search

    object

    The query being made on the logs.

    query [required]

    string

    Search value to apply.

    q

    string

    The widget metrics query.

    queries

    [ <oneOf>]

    List of queries that can be returned directly or used in formulas.

    Option 1

    object

    A formula and functions metrics query.

    aggregator

    enum

    The aggregation methods available for metrics queries. Allowed enum values: avg,min,max,sum,last,area,l2norm,percentile

    cross_org_uuids

    [string]

    The source organization UUID for cross organization queries. Feature in Private Beta.

    data_source [required]

    enum

    Data source for metrics queries. Allowed enum values: metrics

    name [required]

    string

    Name of the query for use in formulas.

    query [required]

    string

    Metrics query definition.

    Option 2

    object

    A formula and functions events query.

    compute [required]

    object

    Compute options.

    aggregation [required]

    enum

    Aggregation methods for event platform queries. Allowed enum values: count,cardinality,median,pc75,pc90,pc95,pc98,pc99,sum,min,max,avg

    interval

    int64

    A time interval in milliseconds.

    metric

    string

    Measurable attribute to compute.

    cross_org_uuids

    [string]

    The source organization UUID for cross organization queries. Feature in Private Beta.

    data_source [required]

    enum

    Data source for event platform-based queries. Allowed enum values: logs,spans,network,rum,security_signals,profiles,audit,events,ci_tests,ci_pipelines,incident_analytics

    group_by

    [object]

    Group by options.

    facet [required]

    string

    Event facet.

    limit

    int64

    Number of groups to return.

    sort

    object

    Options for sorting group by results.

    aggregation [required]

    enum

    Aggregation methods for event platform queries. Allowed enum values: count,cardinality,median,pc75,pc90,pc95,pc98,pc99,sum,min,max,avg

    metric

    string

    Metric used for sorting group by results.

    order

    enum

    Direction of sort. Allowed enum values: asc,desc

    default: desc

    indexes

    [string]

    An array of index names to query in the stream. Omit or use [] to query all indexes at once.

    name [required]

    string

    Name of the query for use in formulas.

    search

    object

    Search options.

    query [required]

    string

    Events search string.

    storage

    string

    Option for storage location. Feature in Private Beta.

    Option 3

    object

    Process query using formulas and functions.

    aggregator

    enum

    The aggregation methods available for metrics queries. Allowed enum values: avg,min,max,sum,last,area,l2norm,percentile

    cross_org_uuids

    [string]

    The source organization UUID for cross organization queries. Feature in Private Beta.

    data_source [required]

    enum

    Data sources that rely on the process backend. Allowed enum values: process,container

    is_normalized_cpu

    boolean

    Whether to normalize the CPU percentages.

    limit

    int64

    Number of hits to return.

    metric [required]

    string

    Process metric name.

    name [required]

    string

    Name of query for use in formulas.

    sort

    enum

    Direction of sort. Allowed enum values: asc,desc

    default: desc

    tag_filters

    [string]

    An array of tags to filter by.

    text_filter

    string

    Text to use as filter.

    Option 4

    object

    A formula and functions APM dependency stats query.

    cross_org_uuids

    [string]

    The source organization UUID for cross organization queries. Feature in Private Beta.

    data_source [required]

    enum

    Data source for APM dependency stats queries. Allowed enum values: apm_dependency_stats

    env [required]

    string

    APM environment.

    is_upstream

    boolean

    Determines whether stats for upstream or downstream dependencies should be queried.

    name [required]

    string

    Name of query to use in formulas.

    operation_name [required]

    string

    Name of operation on service.

    primary_tag_name

    string

    The name of the second primary tag used within APM; required when primary_tag_value is specified. See https://docs.datadoghq.com/tracing/guide/setting_primary_tags_to_scope/#add-a-second-primary-tag-in-datadog.

    primary_tag_value

    string

    Filter APM data by the second primary tag. primary_tag_name must also be specified.

    resource_name [required]

    string

    APM resource.

    service [required]

    string

    APM service.

    stat [required]

    enum

    APM statistic. Allowed enum values: avg_duration,avg_root_duration,avg_spans_per_trace,error_rate,pct_exec_time,pct_of_traces,total_traces_count

    Option 5

    object

    APM resource stats query using formulas and functions.

    cross_org_uuids

    [string]

    The source organization UUID for cross organization queries. Feature in Private Beta.

    data_source [required]

    enum

    Data source for APM resource stats queries. Allowed enum values: apm_resource_stats

    env [required]

    string

    APM environment.

    group_by

    [string]

    Array of fields to group results by.

    name [required]

    string

    Name of this query to use in formulas.

    operation_name

    string

    Name of operation on service.

    primary_tag_name

    string

    Name of the second primary tag used within APM. Required when primary_tag_value is specified. See https://docs.datadoghq.com/tracing/guide/setting_primary_tags_to_scope/#add-a-second-primary-tag-in-datadog

    primary_tag_value

    string

    Value of the second primary tag by which to filter APM data. primary_tag_name must also be specified.

    resource_name

    string

    APM resource name.

    service [required]

    string

    APM service name.

    stat [required]

    enum

    APM resource stat name. Allowed enum values: errors,error_rate,hits,latency_avg,latency_distribution,latency_max,latency_p50,latency_p75,latency_p90,latency_p95,latency_p99

    Option 6

    object

    A formula and functions metrics query.

    additional_query_filters

    string

    Additional filters applied to the SLO query.

    cross_org_uuids

    [string]

    The source organization UUID for cross organization queries. Feature in Private Beta.

    data_source [required]

    enum

    Data source for SLO measures queries. Allowed enum values: slo

    group_mode

    enum

    Group mode to query measures. Allowed enum values: overall,components

    measure [required]

    enum

    SLO measures queries. Allowed enum values: good_events,bad_events,good_minutes,bad_minutes,slo_status,error_budget_remaining,burn_rate,error_budget_burndown

    name

    string

    Name of the query for use in formulas.

    slo_id [required]

    string

    ID of an SLO to query measures.

    slo_query_type

    enum

    Name of the query for use in formulas. Allowed enum values: metric,time_slice

    Option 7

    object

    A formula and functions Cloud Cost query.

    aggregator

    enum

    Aggregator used for the request. Allowed enum values: avg,last,max,min,sum,percentile

    cross_org_uuids

    [string]

    The source organization UUID for cross organization queries. Feature in Private Beta.

    data_source [required]

    enum

    Data source for Cloud Cost queries. Allowed enum values: cloud_cost

    name [required]

    string

    Name of the query for use in formulas.

    query [required]

    string

    Query for Cloud Cost data.

    query

    object

    Updated list stream widget.

    clustering_pattern_field_path

    string

    Specifies the field for logs pattern clustering. Usable only with logs_pattern_stream.

    compute

    [object]

    Compute configuration for the List Stream Widget. Compute can be used only with the logs_transaction_stream (from 1 to 5 items) list stream source.

    aggregation [required]

    enum

    Aggregation value. Allowed enum values: count,cardinality,median,pc75,pc90,pc95,pc98,pc99,sum,min,max,avg,earliest,latest,most_frequent

    facet

    string

    Facet name.

    data_source [required]

    enum

    Source from which to query items to display in the stream. Allowed enum values: logs_stream,audit_stream,ci_pipeline_stream,ci_test_stream,rum_issue_stream,apm_issue_stream,trace_stream,logs_issue_stream,logs_pattern_stream,logs_transaction_stream,event_stream,rum_stream,llm_observability_stream

    default: apm_issue_stream

    event_size

    enum

    Size to use to display an event. Allowed enum values: s,l

    group_by

    [object]

    Group by configuration for the List Stream Widget. Group by can be used only with logs_pattern_stream (up to 4 items) or logs_transaction_stream (one group by item is required) list stream source.

    facet [required]

    string

    Facet name.

    indexes

    [string]

    List of indexes.

    query_string [required]

    string

    Widget query.

    sort

    object

    Which column and order to sort by

    column [required]

    string

    Facet path for the column

    order [required]

    enum

    Widget sorting methods. Allowed enum values: asc,desc

    storage

    string

    Option for storage location. Feature in Private Beta.

    response_format

    enum

    Timeseries, scalar, or event list response. Event list response formats are supported by Geomap widgets. Allowed enum values: timeseries,scalar,event_list

    rum_query

    object

    The log query.

    compute

    object

    Define computation for a log query.

    aggregation [required]

    string

    The aggregation method.

    facet

    string

    Facet name.

    interval

    int64

    Define a time interval in seconds.

    group_by

    [object]

    List of tag prefixes to group by in the case of a cluster check.

    facet [required]

    string

    Facet name.

    limit

    int64

    Maximum number of items in the group.

    sort

    object

    Define a sorting method.

    aggregation [required]

    string

    The aggregation method.

    facet

    string

    Facet name.

    order [required]

    enum

    Widget sorting methods. Allowed enum values: asc,desc

    index

    string

    A coma separated-list of index names. Use "*" query all indexes at once. Multiple Indexes

    multi_compute

    [object]

    This field is mutually exclusive with compute.

    aggregation [required]

    string

    The aggregation method.

    facet

    string

    Facet name.

    interval

    int64

    Define a time interval in seconds.

    search

    object

    The query being made on the logs.

    query [required]

    string

    Search value to apply.

    security_query

    object

    The log query.

    compute

    object

    Define computation for a log query.

    aggregation [required]

    string

    The aggregation method.

    facet

    string

    Facet name.

    interval

    int64

    Define a time interval in seconds.

    group_by

    [object]

    List of tag prefixes to group by in the case of a cluster check.

    facet [required]

    string

    Facet name.

    limit

    int64

    Maximum number of items in the group.

    sort

    object

    Define a sorting method.

    aggregation [required]

    string

    The aggregation method.

    facet

    string

    Facet name.

    order [required]

    enum

    Widget sorting methods. Allowed enum values: asc,desc

    index

    string

    A coma separated-list of index names. Use "*" query all indexes at once. Multiple Indexes

    multi_compute

    [object]

    This field is mutually exclusive with compute.

    aggregation [required]

    string

    The aggregation method.

    facet

    string

    Facet name.

    interval

    int64

    Define a time interval in seconds.

    search

    object

    The query being made on the logs.

    query [required]

    string

    Search value to apply.

    sort

    object

    The controls for sorting the widget.

    count

    int64

    The number of items to limit the widget to.

    order_by

    [ <oneOf>]

    The array of items to sort the widget by in order.

    Option 1

    object

    The formula to sort the widget by.

    index [required]

    int64

    The index of the formula to sort by.

    order [required]

    enum

    Widget sorting methods. Allowed enum values: asc,desc

    type [required]

    enum

    Set the sort type to formula. Allowed enum values: formula

    Option 2

    object

    The group to sort the widget by.

    name [required]

    string

    The name of the group.

    order [required]

    enum

    Widget sorting methods. Allowed enum values: asc,desc

    type [required]

    enum

    Set the sort type to group. Allowed enum values: group

    style [required]

    object

    The style to apply to the widget.

    palette [required]

    string

    The color palette to apply to the widget.

    palette_flip [required]

    boolean

    Whether to flip the palette tones.

    time

     <oneOf>

    Time setting for the widget.

    Option 1

    object

    Wrapper for live span

    live_span

    enum

    The available timeframes depend on the widget you are using. Allowed enum values: 1m,5m,10m,15m,30m,1h,4h,1d,2d,1w,1mo,3mo,6mo,week_to_date,month_to_date,1y,alert

    Option 2

    object

    Used for arbitrary live span times, such as 17 minutes or 6 hours.

    type [required]

    enum

    Type "live" denotes a live span in the new format. Allowed enum values: live

    unit [required]

    enum

    Unit of the time span. Allowed enum values: minute,hour,day,week,month,year

    value [required]

    int64

    Value of the time span.

    Option 3

    object

    Used for fixed span times, such as 'March 1 to March 7'.

    from [required]

    int64

    Start time in seconds since epoch.

    to [required]

    int64

    End time in seconds since epoch.

    type [required]

    enum

    Type "fixed" denotes a fixed span. Allowed enum values: fixed

    title

    string

    The title of your widget.

    title_align

    enum

    How to align the text on the widget. Allowed enum values: center,left,right

    title_size

    string

    The size of the title.

    type [required]

    enum

    Type of the geomap widget. Allowed enum values: geomap

    default: geomap

    view [required]

    object

    The view of the world that the map should render.

    focus [required]

    string

    The 2-letter ISO code of a country to focus the map on. Or WORLD.

    {
  "custom_links": [
    {
      "is_hidden": false,
      "label": "Search logs for {{host}}",
      "link": "https://app.datadoghq.com/logs?query={{host}}",
      "override_label": "logs"
    }
  ],
  "requests": [
    {
      "columns": [
        {
          "field": "content",
          "is_clustering_pattern_field_path": true,
          "width": "compact"
        }
      ],
      "formulas": [
        {
          "alias": "string",
          "cell_display_mode": "number",
          "conditional_formats": [
            {
              "comparator": ">",
              "custom_bg_color": "string",
              "custom_fg_color": "string",
              "hide_value": false,
              "image_url": "string",
              "metric": "string",
              "palette": "blue",
              "timeframe": "string",
              "value": 0
            }
          ],
          "formula": "func(a) + b",
          "limit": {
            "count": "integer",
            "order": "string"
          },
          "style": {
            "palette": "classic",
            "palette_index": 1
          }
        }
      ],
      "log_query": {
        "compute": {
          "aggregation": "avg",
          "facet": "@duration",
          "interval": 5000
        },
        "group_by": [
          {
            "facet": "resource_name",
            "limit": 50,
            "sort": {
              "aggregation": "avg",
              "facet": "@string_query.interval",
              "order": "desc"
            }
          }
        ],
        "index": "days-3,days-7",
        "multi_compute": [
          {
            "aggregation": "avg",
            "facet": "@duration",
            "interval": 5000
          }
        ],
        "search": {
          "query": ""
        }
      },
      "q": "string",
      "queries": [],
      "query": {
        "clustering_pattern_field_path": "message",
        "compute": [
          {
            "aggregation": "count",
            "facet": "resource_name"
          }
        ],
        "data_source": "apm_issue_stream",
        "event_size": "string",
        "group_by": [
          {
            "facet": "resource_name"
          }
        ],
        "indexes": [],
        "query_string": "@service:app",
        "sort": {
          "column": "",
          "order": "desc"
        },
        "storage": "indexes"
      },
      "response_format": "timeseries",
      "rum_query": {
        "compute": {
          "aggregation": "avg",
          "facet": "@duration",
          "interval": 5000
        },
        "group_by": [
          {
            "facet": "resource_name",
            "limit": 50,
            "sort": {
              "aggregation": "avg",
              "facet": "@string_query.interval",
              "order": "desc"
            }
          }
        ],
        "index": "days-3,days-7",
        "multi_compute": [
          {
            "aggregation": "avg",
            "facet": "@duration",
            "interval": 5000
          }
        ],
        "search": {
          "query": ""
        }
      },
      "security_query": {
        "compute": {
          "aggregation": "avg",
          "facet": "@duration",
          "interval": 5000
        },
        "group_by": [
          {
            "facet": "resource_name",
            "limit": 50,
            "sort": {
              "aggregation": "avg",
              "facet": "@string_query.interval",
              "order": "desc"
            }
          }
        ],
        "index": "days-3,days-7",
        "multi_compute": [
          {
            "aggregation": "avg",
            "facet": "@duration",
            "interval": 5000
          }
        ],
        "search": {
          "query": ""
        }
      },
      "sort": {
        "count": "integer",
        "order_by": [
          {
            "index": 0,
            "order": "desc",
            "type": "formula"
          }
        ]
      }
    }
  ],
  "style": {
    "palette": "hostmap_blues",
    "palette_flip": false
  },
  "time": {
    "live_span": "5m"
  },
  "title": "string",
  "title_align": "string",
  "title_size": "string",
  "type": "geomap",
  "view": {
    "focus": "WORLD"
  }
}

    Further Reading

    Additional helpful documentation, links, and articles:

    Building Dashboards using JSONDOCUMENTATION more more NotebooksDOCUMENTATION more more