Custom Map Files

Chart Tutorials  

Custom Map Files

Using 3rd party geoJSON and topoJSON map files.

🔗Using custom map files directly.

Map files can be used to populate series points like so

{
  series: [
    {
      map: "mapData/usCapitals.json.txt"
    }
  ];
}
Please note that in samples we use usCapitals.json.txt text file extension as a workaround for json mime types not being included by default with many server setups. In order to use this file, use the .txt extension or rename it.

🔗Custom map file reference.

Custom map files can be used in their entirety, or just specific map features defined in those files can be used on a chart.

In order to use only some map features from a custom map file, the map file must be made available to the chart through the mapping.referenceLayers property.

{
  mapping: {
    referenceLayers: "mapData/usCapitals.json.txt";
  }
}

Now, series and points can refer to map features defined in this reference layer using mapCodes or propertyFilters.

Both geoJSON and topoJSON file formats are supported. They can be specified using a relative path. When a custom map file is specified for a series, a point is generated for each feature in that map file.

🔗Reference layer mapCodes

Using in a series

When a map file path is specified in a referenceLayer, this file can be subsequently be referred to by its filename without extension. In this example it is "usCapitals".

The following code creates a series with points for each map feature in the usCapitals.json file.

{
  series: [
    {
      map: "usCapitals"
    }
  ];
}

The above example has the same effect as the first snippet on this page.

🔗By map feature IDs

The following code creates a point based on a map feature defined in the usCapitals file that has the ID of 'springfield'.

{
  series: [
    {
      //indicates a map feature in the usCapitals map with an id of 'springfield'
      points: [{ map: "usCapitals.springfield" }]
    }
  ];
}
If a filename contains multiple periods, the part before the first period becomes the id.

🔗Reference layer propertyFilters

Series from propertyFilters

A series can also be created from all map features with a property matching a specific value.

{
  series: [
    {
      map: "usCapitals.region:west"
    }
  ];
}

In this example, points are created for each map feature in the usCapitals file where the region property matches 'west'.

Similarly, points for specific map features can be defined to modify those points or to add additional points to a series.

{
  series: [
    {
      map: "usCapitals.region:west",
      points: [
        {
          map: "usCapitals.springfield",
          color: "red"
        }
      ]
    }
  ];
}
For more information on binding data to custom map files, see the following tutorial.
Map Data Binding Tutorial Using maps to visualize data.