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"
    }
  ]
}

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.

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" }]
    }
  ]
}

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.