Country Data Mode

Highlights countries with fill colors and data labels. Perfect for choropleth visualizations, trade statistics, and geopolitical content.

Basic Example

{
  "mode": "country_data",
  "country_data": {
    "countries": [
      { "iso_code": "CN", "fill_color": "#E63946", "name": "China", "data_label": "45%" },
      { "iso_code": "US", "fill_color": "#1D3557", "name": "USA", "data_label": "25%" },
      { "iso_code": "DE", "fill_color": "#457B9D", "name": "Germany", "data_label": "15%" }
    ]
  },
  "style": "geopolitics",
  "duration": 15
}

Country Properties

Property	Type	Required	Description
`iso_code`	string	required	2-letter ISO country code (e.g., "US", "CN", "DE")
`fill_color`	string	required	Fill color (hex)
`name`	string	optional	Country display name
`data_label`	string	optional	Data annotation (e.g., "45%", "$2.5B")
`fill_opacity`	number	optional	Fill opacity (0-1, default: 0.7)
`label_position`	object	optional	`{ lat, lng }` - Required for labels to appear

Important: Labels only appear if you specify label_position. This is typically the country's centroid or capital coordinates.

Camera Settings

{
  "country_data": {
    "countries": [...],
    "camera": {
      "start_zoom": 1.5,
      "end_zoom": 2.5,
      "rotation_degrees": 0,
      "center": { "lat": 30, "lng": 0 }
    }
  }
}

Label Settings

{
  "country_data": {
    "countries": [...],
    "labels": {
      "animate": true,
      "show_country_names": true,
      "show_data_labels": true
    }
  }
}

Animation Timing

Control when fills and labels appear:

{
  "country_data": {
    "countries": [...],
    "animation": {
      "camera_start_seconds": 0,
      "fill_start_seconds": 1,
      "fill_duration_seconds": 2,
      "labels_start_seconds": 3,
      "labels_stagger_seconds": 0.3
    }
  }
}

Property	Default	Description
`camera_start_seconds`	0	When camera zoom begins
`fill_start_seconds`	0	When country fills appear
`fill_duration_seconds`	2	Fill fade-in duration
`labels_start_seconds`	auto	When labels appear
`labels_stagger_seconds`	0.3	Delay between each label

Common ISO Codes

Country	ISO Code
United States	`US`
China	`CN`
Germany	`DE`
Japan	`JP`
United Kingdom	`GB`
France	`FR`
India	`IN`
Brazil	`BR`
Australia	`AU`
Russia	`RU`

Use standard ISO 3166-1 alpha-2 codes.

Use Cases

Trade statistics: Import/export percentages by country
Market share: Revenue or users by region
Election maps: Voting results by country
Sanctions visualization: Affected countries highlighted
Supply chain: Manufacturing locations

Complete Example

{
  "mode": "country_data",
  "country_data": {
    "countries": [
      {
        "iso_code": "CN",
        "fill_color": "#E63946",
        "name": "China",
        "data_label": "45%",
        "label_position": { "lat": 35, "lng": 105 }
      },
      {
        "iso_code": "US",
        "fill_color": "#1D3557",
        "name": "USA",
        "data_label": "25%",
        "label_position": { "lat": 39, "lng": -98 }
      },
      {
        "iso_code": "DE",
        "fill_color": "#457B9D",
        "name": "Germany",
        "data_label": "15%",
        "label_position": { "lat": 51, "lng": 10 }
      },
      {
        "iso_code": "JP",
        "fill_color": "#2A9D8F",
        "name": "Japan",
        "data_label": "10%",
        "label_position": { "lat": 36, "lng": 138 }
      },
      {
        "iso_code": "KR",
        "fill_color": "#E9C46A",
        "name": "South Korea",
        "data_label": "5%",
        "label_position": { "lat": 36, "lng": 128 }
      }
    ],
    "camera": {
      "start_zoom": 1.2,
      "end_zoom": 2,
      "rotation_degrees": 0
    },
    "labels": {
      "animate": true,
      "show_country_names": true
    },
    "animation": {
      "fill_start_seconds": 1,
      "fill_duration_seconds": 2,
      "labels_start_seconds": 3,
      "labels_stagger_seconds": 0.4
    }
  },
  "style": "geopolitics",
  "duration": 15,
  "text_overlays": [
    {
      "text": "Global Semiconductor Production 2026",
      "position": "top-center",
      "start_time": 0,
      "end_time": 4,
      "font_size": 32
    }
  ]
}