Maps¶

Maps are worksheet configurations with a map object. The compiler supports two geometry families:

Generated geography maps from declared geographic roles.
Explicit coordinate maps from latitude/longitude measures.

Do not invent spatial-file, custom geocoding, or arbitrary Tableau map-layer surfaces unless fixtures and Desktop proof exist.

Map Object¶

{
  "name": "Filled Sales Map",
  "datasource": "Orders",
  "map": {
    "kind": "filled",
    "geometry": "generated",
    "geography": [
      "[Orders].[State/Province]",
      "[Orders].[Country/Region]"
    ]
  },
  "encodings": {
    "color": {
      "field": "[Orders].[Sales]",
      "aggregation": "sum"
    },
    "tooltip": {
      "field": "[Orders].[Sales]",
      "aggregation": "sum"
    }
  }
}

Field	Type	Required	Values	Description
`kind`	string	Yes	`filled`, `symbol`, `point`, `density`, `flow`	Map template kind.
`geometry`	string	Yes	`generated`, `coordinates`	Geometry source. `filled` and `symbol` require `generated`; `point`, `density`, and `flow` require `coordinates`.
`geography`	array	Generated maps only	Field refs	Geographic fields with declared `geographic_role`.
`latitude`	object	Coordinate maps only	Coordinate aggregate	Latitude measure. Must aggregate with `avg`.
`longitude`	object	Coordinate maps only	Coordinate aggregate	Longitude measure. Must aggregate with `avg`.
`detail`	array	Required for `density`; optional for `point`/`flow`	Field refs	Fields used to identify coordinate marks.
`background_layers`	object	No	Background layer toggles	Controls Desktop-proven map background layers.

Map Kinds¶

Kind	Geometry	Required fields	Notes
`filled`	`generated`	`geography`	Filled geography polygons. Current Desktop-proven generated geography roles are country and state/province.
`symbol`	`generated`	`geography`	Generated symbol maps. Supports country, state/province, city, and zip/postal roles.
`point`	`coordinates`	`latitude`, `longitude`	Explicit coordinate point map.
`density`	`coordinates`	`latitude`, `longitude`, `detail`	Explicit coordinate density map.
`flow`	`coordinates`	`latitude`, `longitude`, `encodings.path`	Route/flow map. Detail is optional but usually useful for route identity.

Generated maps must not include latitude, longitude, or detail. Coordinate maps must not include geography.

Coordinate Aggregate¶

Field	Type	Required	Values	Description
`field`	string	Yes	Latitude or longitude measure ref	Numeric coordinate field.
`aggregation`	string	Yes	`avg`	Coordinate aggregation.

{
  "latitude": {
    "field": "[Stores].[Latitude]",
    "aggregation": "avg"
  },
  "longitude": {
    "field": "[Stores].[Longitude]",
    "aggregation": "avg"
  }
}

Geographic Roles¶

Geographic roles live on datasource columns, not on worksheets.

`geographic_role`	Supported map use
`country_iso3166_2`	Generated filled and symbol maps.
`state_name`	Generated filled and symbol maps. State-level maps need a country field or datasource `semantic_values.country_name`.
`city_name`	Generated symbol maps.
`zip_code_name`	Generated symbol maps.

{
  "columns": [
    {
      "name": "Country/Region",
      "role": "dimension",
      "type": "nominal",
      "datatype": "string",
      "geographic_role": "country_iso3166_2"
    },
    {
      "name": "State/Province",
      "role": "dimension",
      "type": "nominal",
      "datatype": "string",
      "geographic_role": "state_name"
    }
  ],
  "semantic_values": [
    {
      "key": "country_name",
      "value": "United States"
    }
  ]
}

Background Layers¶

background_layers is a map object whose keys are layer names and whose values are booleans.

Field	Type	Values	Description
`roads`	boolean	`true`, `false`	Road layer.
`coastline`	boolean	`true`, `false`	Coastline layer.
`country_boundaries`	boolean	`true`, `false`	Country boundary layer.
`country_labels`	boolean	`true`, `false`	Country label layer.
`state_boundaries`	boolean	`true`, `false`	State/province boundary layer.
`state_labels`	boolean	`true`, `false`	State/province label layer.
`us_state_abbreviations`	boolean	`true`, `false`	US state abbreviation labels.
`water_lines`	boolean	`true`, `false`	Water line layer.
`land_cover`	boolean	`true`, `false`	Land cover layer.
`parks`	boolean	`true`, `false`	Parks layer.

{
  "background_layers": {
    "roads": true,
    "state_labels": true,
    "parks": false
  }
}

Map Encodings¶

Map worksheets use the normal encodings object with map-specific constraints.

Encoding	Applies To	Values	Notes
`color`	All map kinds	Field ref, aggregate, or palette object	Use categorical color for dimensions or continuous palettes for measures.
`size`	`point`, `symbol`, `flow`	Aggregate object	Mark size.
`tooltip`	All map kinds	Field ref or aggregate object	Tooltip field.
`detail`	Coordinate maps	Field refs	Usually use `map.detail` for coordinate identity.
`path`	`flow`	Field ref	Required for flow maps; usually route step/order.

Filled Map Example¶

{
  "name": "State Sales Map",
  "datasource": "Orders",
  "map": {
    "kind": "filled",
    "geometry": "generated",
    "geography": [
      "[Orders].[State/Province]",
      "[Orders].[Country/Region]"
    ]
  },
  "encodings": {
    "color": {
      "field": "[Orders].[Sales]",
      "aggregation": "sum",
      "palette": {
        "kind": "continuous",
        "name": "tableau-orange-blue",
        "center": 0
      }
    },
    "tooltip": {
      "field": "[Orders].[Profit]",
      "aggregation": "sum"
    }
  },
  "formatting": [
    {
      "element": "map",
      "formats": [
        {
          "attr": "map-style",
          "value": "light"
        },
        {
          "attr": "washout",
          "value": 85
        }
      ]
    }
  ]
}

Symbol Map Example¶

{
  "name": "City Sales Symbols",
  "datasource": "Orders",
  "map": {
    "kind": "symbol",
    "geometry": "generated",
    "geography": [
      "[Orders].[City]",
      "[Orders].[State/Province]",
      "[Orders].[Country/Region]"
    ]
  },
  "encodings": {
    "color": "[Orders].[Segment]",
    "size": {
      "field": "[Orders].[Sales]",
      "aggregation": "sum"
    }
  }
}

Point And Density Examples¶

[
  {
    "name": "Store Sales Point Map",
    "datasource": "Stores",
    "map": {
      "kind": "point",
      "geometry": "coordinates",
      "latitude": {
        "field": "[Stores].[Latitude]",
        "aggregation": "avg"
      },
      "longitude": {
        "field": "[Stores].[Longitude]",
        "aggregation": "avg"
      },
      "detail": ["[Stores].[Store]"],
      "background_layers": {
        "roads": true,
        "state_labels": true
      }
    },
    "encodings": {
      "color": "[Stores].[Region]",
      "size": {
        "field": "[Stores].[Sales]",
        "aggregation": "sum"
      }
    }
  },
  {
    "name": "Customer Density Map",
    "datasource": "Customers",
    "map": {
      "kind": "density",
      "geometry": "coordinates",
      "latitude": {
        "field": "[Customers].[Latitude]",
        "aggregation": "avg"
      },
      "longitude": {
        "field": "[Customers].[Longitude]",
        "aggregation": "avg"
      },
      "detail": ["[Customers].[Customer ID]"]
    },
    "encodings": {
      "color": {
        "field": "[Customers].[Sales]",
        "aggregation": "sum"
      }
    }
  }
]

Flow Map Example¶

{
  "name": "Route Flow Map",
  "datasource": "Routes",
  "map": {
    "kind": "flow",
    "geometry": "coordinates",
    "latitude": {
      "field": "[Routes].[Latitude]",
      "aggregation": "avg"
    },
    "longitude": {
      "field": "[Routes].[Longitude]",
      "aggregation": "avg"
    },
    "detail": ["[Routes].[Route]"],
    "background_layers": {
      "roads": true,
      "state_labels": true
    }
  },
  "encodings": {
    "path": "[Routes].[Step]",
    "color": "[Routes].[Route]",
    "size": {
      "field": "[Routes].[Volume]",
      "aggregation": "sum"
    },
    "tooltip": {
      "field": "[Routes].[Volume]",
      "aggregation": "sum"
    }
  }
}

Map Layer Formatting¶

Use worksheet formatting for supported map styles.

Element	Attr	Values	Description
`map`	`map-style`	`light`	Base map style.
`map`	`washout`	number	Base map washout.
`map-data-layer`	`palette`	`tableau-map-blue-green-light`	Data layer palette.

{
  "formatting": [
    {
      "element": "map-data-layer",
      "formats": [
        {
          "attr": "palette",
          "value": "tableau-map-blue-green-light"
        }
      ]
    }
  ]
}