World Map Management

Overview

World Map Management is used to maintain the region mapping relationships and map data files of the World Map. After configuration is complete, the World Map can identify the map level to display based on region names or region codes in business data, and load the corresponding GeoJSON map data.

For example, when the region value in business data is "California", it first identifies its region code as US-CA, then finds its parent region code as US based on US-CA, thereby loading US.json, and finally renders the US map and shades the "California" region.

The configuration interface is as follows:

Note

This feature only supports World Maps rendered based on ECharts.

Configuration Instructions

Region Code

Region codes should use unique strings. It is recommended to use only English letters, numbers, and hyphens without spaces, and they are case-sensitive.

Region codes are used in the following places:

• textToCode values
• codeToUpperCode keys and values
• Map data file names
• feature.properties.code in map data files

Region codes are recommended to use naming conventions that reflect hierarchy such as US, US-CA, US-CA-LA, but the actual parent-child relationship is still determined by the codeToUpperCode configuration.

Relationship Between Files

The following two types of files are needed to implement custom region map rendering:

File	Purpose	Naming Requirement
world-geo-map.json	Maintains business region names, unique region identifiers, and parent-child region relationships	File name is fixed and cannot be modified
Map data files	Stores GeoJSON boundary data for the subordinate regions of a specific region	File name must match the region code of that region, e.g., US.json is used to load the map of the United States

The system identifies and loads maps in the following order:

1. Convert business region names to region codes based on world-geo-map.json.
2. Find the parent region code based on the region code.
3. Load the map data file named after the parent region code.
4. Associate business data based on the code of each region in the "map data JSON", and use name to display the region name.

Using "California" as an example:

California → US-CA → Parent region US → Load US.json → Match the region with code US-CA in the map JSON file

Mapping Relationship File

The mapping relationship file is fixed as world-geo-map.json. It can be downloaded on the World Map Management page. The file contains the following two objects:

• textToCode: Defines the mapping between business region names and region codes. The same region can be configured with Chinese names, English names, or business names used within the enterprise.
• codeToUpperCode: Defines the relationship between region codes and parent region codes. The system determines which map data file to load based on this relationship.

The following example supplements the names and parent-child relationships for California and Los Angeles County based on the system's built-in US mapping:

{
  "textToCode": {
    "加利福尼亚州": "US-CA",
    "California": "US-CA",
    "洛杉矶县": "US-CA-LA",
    "Los Angeles County": "US-CA-LA"
  },
  "codeToUpperCode": {
    "US-CA": "US",
    "US-CA-LA": "US-CA"
  }
}

You can download the base-world-geo-map to view the commonly used Chinese and English names, region codes, and parent-child relationships for countries or regions already supported by the system. This file is for reference only and does not need to be modified or uploaded.

In the world-geo-map.json maintained by the user, only the following content needs to be filled in:

• Region names, region codes, or parent-child relationships not included in the system built-in mapping.
• Names, region codes, or parent-child relationships that need to override the system built-in mapping.

The mapping relationship configuration uploaded by the user will be merged with the system built-in mapping; when the same name or region code exists, the user's uploaded configuration takes precedence.

When maintaining the mapping relationship file, please note:

• The world-geo-map.json file name is fixed and can only be maintained in the Mapping Relation area.
• Before modifying, please download the current file from the system first, then add or modify based on the existing content to avoid overwriting custom mappings already maintained by other users.
• Region fields in business data can also directly use region codes such as US-CA. In this case, the value does not need to be configured repeatedly in textToCode, but its parent region still needs to be configured in codeToUpperCode so that the system can determine which map file to load.

Map Data File

Map data files use GeoJSON format. Each feature.properties must contain at least:

• code: The region code of the current region (note the uniqueness), used to associate business data.
• name: The name of the current region displayed on the map.

For example, California in US.json can be defined as follows:

{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "properties": {
        "code": "US-CA",
        "name": "California"
      },
      "geometry": {
        "type": "Polygon",
        "coordinates": []
      }
    }
  ]
}

The coordinates in the above code are only used to illustrate the file structure. In actual use, complete and valid GeoJSON coordinates need to be filled in.

Map data files follow the rule of "file name equals current map code":

Region to Display	Region Code Corresponding to Business Data	Parent Region Code	Map File to Upload
Countries or regions around the world	US, CN, etc.	world1	world1.json
US states	US-CA, US-NY, etc.	US	US.json
Subordinate regions of California	US-CA-LA, etc.	US-CA	US-CA.json

When maintaining map data files, please note:

• A single map data file only supports JSON format, with a file size not exceeding 10 MB. Before uploading, please use tools to compress or trim coordinate point accuracy as much as possible to reduce map loading pressure.
• The file name must match the corresponding region code; apart from the .json suffix, it can only contain letters, numbers, and hyphens.
• When batch importing, individual JSON files in the compressed package must still comply with the above rules.
• When adding or batch importing files with the same name, the system will overwrite existing files.
• Updating existing files only replaces the file content, not the original file name in the list.
• After deleting a map data file, subordinate maps that depend on that file will not be able to load.

File Content Validation

The upload page only validates file type, size, and file name, and does not validate JSON syntax, GeoJSON coordinates, or whether code and name are complete. It is recommended to use a JSON or GeoJSON validation tool to check the file before uploading. Missing code or incorrect parent-child relationship configuration may cause the map to fail to generate, regions to fail to shade, or map loading to fail after drilldown.

Usage Examples

The following example shows the effect after drilldown to the US. The business data, mapping relationships, and map data required for the example can be referenced at: world-map-example.

World-level display effect:

Effect after drilldown to US state-level regions:

Effect after further drilldown to subordinate regions of California:

Troubleshooting

Chart shows "The geographic location information configured in the current chart cannot be recognized"

Please check in the following order:

1. Whether the business region name has been configured in textToCode, or whether the business data directly uses a valid region code.
2. Whether the parent region of the region code has been configured in codeToUpperCode.
3. Whether world-geo-map.json is valid JSON and the field names are correct.

Map fails to load after drilldown

Please check whether the corresponding map file has been uploaded. For example, displaying US states requires uploading US.json; displaying subordinate regions of California requires uploading US-CA.json.

Also confirm that the file name exactly matches the codeToUpperCode configuration, including case.

Map can be opened, but some regions are not shaded

Please check:

• Whether the region code after business data conversion is exactly consistent with feature.properties.code in GeoJSON.
• Whether code and name are included in GeoJSON.
• Whether the current dimension data is mixed with data from other levels or other parent regions.
• Whether there are extra spaces, different language spellings, or enterprise custom aliases in business region names; if so, please add mappings in textToCode.