Creating Custom Vector Maps (Region Maps) Visualization

Region maps can be created using default vector maps or custom vector maps. The default vector maps cover the majority of the use cases, but if you have any requirements that are not covered by vector maps, you can use custom vector maps. To create custom vector maps, a GeoJSON file with the required vectors needs to be imported.

For more information on custom GeoJSON, refer to the OpenSearch blog (https://opensearch.org/blog/whatsnew-custom-geo-json/).

To import a custom vector map, complete the following steps:

  1. Create a JSON file to upload.

    Note:

    The JSON file must have .geojson or .json as an extension.

  2. In OpenSearch Dashboards, select Create Visualization to create a region map visualization.

  3. In the right panel, select Import Vector Map.

  4. Browse and select the .geojson file to import.

  5. Enter the file name (lowercase and numbers only).

  6. Click the Import file button.

    If the file import is successful, the system displays a success message.

  7. Click the Refresh button to refresh the page.

    At this point, your custom region map is created, and you can use it by following these steps:

  8. Navigate to the Layer Options tab, and select Custom vector map.

  9. In the Vector map section, select the vector map that you just imported.

    Note:

    The maximum file size that can be imported is 25 MB, and the maximum number of features that can be imported is 10,000.

  10. Click the Update button.

Consider the following points when you create region maps:

  • The region map visualization uses OpenStreetMap and Natural Earth APIs and data for creating region maps.

  • OpenSearch default vector maps do not have some join fields, such as FIPS 5-2 alpha for US states. The default vector map of USA states can be used with the join field "name (en)" instead of state codes. It is recommended that the indexed data includes a field with state name to which the vector can be mapped.

  • OpenSearch region maps do not support the vector map for postal codes.

Example of GeoJSON File

The following is an example of GeoJSON file.

{
  "type": "FeatureCollection",
  "name": "usa counties",
  "features": [
    { "type": "Feature", "properties": { "iso2": "US", "iso3": "SF-CA", "name": "San Francisco County", "country": "US", "county": "SF" }, "geometry": { "type": "Polygon", "coordinates":[xxxx] } },
    { "type": "Feature", "properties": { "iso2": "US", "iso3": "SC-CA", "name": "Santa Cruz County", "country": "US", "county": "SC" }, "geometry": { "type": "Polygon", "coordinates":[xxxx] } }
  ]
}