ZoomCharts Documentation
Version: 1.21.3 (2025-04-07)
Switch to Version 2.0 (BETA)

Data format

Concept explanation

First, you should keep in mind that GeoChart is built from layers. You can add multiple layers. Each layer can represent something else and so different data source can be applied to each layer.

For instance one layer can represent country shapes, other layer nodes, links or even other charts. For more information about charts-on-charts feature can be found here.

Keepind this in mind, data can be either object or array of objects. In case multiple data sources are used, ID must be provided.

Learn more about multiple data source usage and data referencing with layers here.

Typical data formats

As it is possible to display different kind of information on the map (like: country shapes, nodes or points,nodes with links,custom shapes,charts) then there is slightly different data object structure.

Nodes (points) with links

One of most common data objects looks like this:

    {
        nodes: [
            { id: "Squaw Valley", coordinates: [-119.181449, 36.707146] },
            { id: "Atlanta", coordinates: [-84.388846, 33.752504] },
            { id: "New York", coordinates: [-73.996705, 40.74838] },
            { id: "Lake Placid", coordinates: [-81.364918, 27.294474] }
        ],
        links: [
            { from: "New York", to: "Atlanta", drivingTime: "13 hours 3 mins" },
            { from: "New York", to: "Squaw Valley", drivingTime: "1 day 18 hours" },
            { from: "New York", to: "Lake Placid", drivingTime: "17 hours 33 mins" },
            { from: "Lake Placid", to: "Squaw Valley", drivingTime: "1 day 15 hours" },
            { from: "Atlanta", to: "Squaw Valley", drivingTime: "1 day 10 hours" }
        ]
    }

In this case some points linked together will appear on the map.

Each node object must have the following fields:

Each link object should have following fields:

Links:

Optional specific node fields:

Nodes and links can contain any other fields that can be used later by the user either to build custom look. Nodes can have an optional style object that defines the look of the object. See style section on for more info.

Shapes

For shapes you should use geoJson object structure. With geoJson you can create custom shapes like triangles, lines etc. The same approach is used when creating countries or regions.

    {
        "type": "FeatureCollection",
        "features": [
            {
                "type":"Feature",
                "id":"shape-id",
                "properties": {"name":"Custom Shape"}, 
                "geometry": {
                "type":"Polygon",
                "coordinates": [
                    [
                        [50.20, 20.65],
                        [30.65, -22.15],
                        [-80.83, 52.10],
                        [-40.32, 70.27]
                    ]
                ]
            }
        }
    }

When using geoJson, you need to explicitly set data.format = "GeoJSON". Like in this example:

    data: {
        preloaded: {
            //GeoJson data
        },
        format: "GeoJSON",
        perBoundsData: false
    }

perBoundsData is described here and also further on in this page.

Aggregated nodes and charts-on-charts

Information about displaying charts like FacetChart, PieChart or aggregated values over the GeoChart is described in this section.

Styling

Basically you can add style object for each node. Set style.fillColor for fill and style.lineColor for outline. More detailed settings you will find here in full reference;

Static or preloaded data

You can specify static data, using the data.preloaded setting.

For example:

    chart = new GeoChart({
      data:{
        preloaded: {
          nodes: [...],
        }
      }
      /* ... */
    });

Incremental loading

For big data sets it's not reasonable to load all network at once. To solve this Geo Chart is able to dynamically load data on demand.

Use the following settings:

    chart = new GeoChart({
      data:{
        url:"myDataService.php"
        dataFunction:function(nodeIds, success, error){...}
      },
      navigation:{
        initialLat: 35.1,
        initialLng: 44.3,
        initialZoom: 6
      }
      ...
    });

Choose either data.url or data.dataFunction.

Set navigation.initialLat to initial latitude, navigation.initialLng to initial longitude and navigation.initialZoom to desired zoom value (0..18). See Navigation for more info on navigation mode.

Upon creation Geo Chart requests initial set of nodes for initial display region. The settings.data has many more options that control the data loading. See Api Reference for a full list.

Data request

Data URL parameters:

Data function parameters:

Bounds parameters can be null, that signifies that data over whole map are requested.

Data response fields:

The function must return immediately and use success(data) and error() callbacks to return data. Calling success(data) immediately is also okay.

Server can return data over bigger or smaller area than requested by specifying west, north, east, south, parameters in response. The data will be stored in cache and used without performing additional server requests.

Data polling strategies

Depending on the amount of data, and your server capabilities, you may want to implement lazy loading of data.

    var options = {
      /* ... */
      data: {
        /* ... */
        perBoundsData: true,
        perZoomData: false,
        perDrilldownData: false
      }
    };

By changing these attributes attributes, you can control how ZoomCharts will poll the data upon chart navigation.

Merging data

Nodes can repeat over multiple requests. If node id's match old data is replaced.

Nodes that overlap request bounds but are not present in data are deleted from chart.

X