Highlighting

Create quiz-ready maps with highlighted regions.

Highlighting Regions

Highlight specific states, provinces, or regions on your maps. Perfect for geography quizzes and educational materials.

How It Works

Add highlight_subdivisions to your map configuration to highlight specific regions with custom colors.

Basic Example

Highlight Idaho on a US map:

curl -X POST 'https://api.smavatar.com/api/v1/projects/{project_id}/jobs/maps' \
  -H 'Authorization: Bearer {api_key}' \
  -H 'Content-Type: application/json' \
  -d '{
    "location_id": "bdd56f14-e776-418a-ab18-89c8138df978",
    "width": 1400,
    "height": 900,
    "theme": "modern",
    "output_format": "png",
    "configuration": {
      "highlight_subdivisions": [
        {
          "subdivision_code": "us-id",
          "fill_color": "#3498db",
          "opacity": 0.7,
          "show_label": true
        }
      ]
    }
  }'

Highlight Options

Each highlight object accepts:

Field	Type	Default	Description
`subdivision_code`	string	required	ISO code (e.g., `us-ca`)
`fill_color`	string	`#3498db`	Hex color for fill
`opacity`	number	0.5	Fill opacity (0-1)
`show_label`	boolean	false	Show region name

Multiple Highlights

Highlight multiple regions with different colors:

{
  "configuration": {
    "highlight_subdivisions": [
      {
        "subdivision_code": "us-ca",
        "fill_color": "#e74c3c",
        "opacity": 0.7,
        "show_label": false
      },
      {
        "subdivision_code": "us-tx",
        "fill_color": "#2ecc71",
        "opacity": 0.7,
        "show_label": false
      },
      {
        "subdivision_code": "us-ny",
        "fill_color": "#9b59b6",
        "opacity": 0.7,
        "show_label": false
      }
    ]
  }
}

Quiz Mode

Create quiz maps with highlights but no labels:

{
  "configuration": {
    "show_subdivision_labels": false,
    "show_country_labels": false,
    "highlight_subdivisions": [
      {
        "subdivision_code": "us-id",
        "fill_color": "#3498db",
        "opacity": 0.7,
        "show_label": false
      }
    ]
  }
}

Then create an "answer key" version:

{
  "configuration": {
    "show_subdivision_labels": true,
    "highlight_subdivisions": [
      {
        "subdivision_code": "us-id",
        "fill_color": "#3498db",
        "opacity": 0.7,
        "show_label": true
      }
    ]
  }
}

Color Suggestions

For educational materials, use distinct, accessible colors:

Purpose	Color	Hex
Primary highlight	Blue	`#3498db`
Correct answer	Green	`#2ecc71`
Wrong answer	Red	`#e74c3c`
Secondary	Purple	`#9b59b6`
Accent	Orange	`#e67e22`

Full Quiz Example

Step 1: Get Subdivision Codes

curl 'https://api.smavatar.com/api/mcp/tools/list-locations?type=subdivision&q=pacific'

Step 2: Create Quiz Map (No Labels)

curl -X POST '.../jobs/maps' \
  -d '{
    "location_id": "bdd56f14-e776-418a-ab18-89c8138df978",
    "theme": "modern",
    "configuration": {
      "show_subdivision_labels": false,
      "highlight_subdivisions": [
        {
          "subdivision_code": "us-wa",
          "fill_color": "#3498db",
          "opacity": 0.6
        },
        {
          "subdivision_code": "us-or",
          "fill_color": "#2ecc71",
          "opacity": 0.6
        },
        {
          "subdivision_code": "us-ca",
          "fill_color": "#e74c3c",
          "opacity": 0.6
        }
      ]
    }
  }'

Step 3: Create Answer Key (With Labels)

Same request, but with show_label: true on each highlight.

Limits

Maximum 50 highlights per map
Subdivision must belong to the map's location
Invalid codes return validation errors

Next Steps

Themes

Choose the right visual style for your map.

Rivers & Lakes

Add hydrological features.

Locations

Finding countries, states, and cities for map generation.

Themes

Visual themes for map generation.