You are viewing documentation for an older version. For current documentation - click here.
Quick Map Configuration

This section is a guide to the various objects that a map is comprised of and to the structure of the XML/JSON data FusionMaps XT accepts.

If you're a non-technical user and want to generate maps without using any programs or scripts, you can switch to Using Visual Map Builder page, where we explain how to visually configure and generate a data-driven map, without getting into any programming.

Let's now take a pictorial tour of each object before we go into more details.

Map objects

Each map of FusionMaps XT pack comprises of a number of objects of which the important ones are :

Entity

An entity for a map is the smallest item that we're dealing with on the map. For example, in a World Map showing continents, each continent is an entity. In a continent map showing countries, each country is referred to as an entity. Similarly, if a country map is showing states, each state is referred to as an entity.

For each map each entity has an unique identifier. We call it internalId of the entity. For example, in World map the internalId of North America is NA, ASIA is AS; in Europe map the internalId of UK is 042 etc. To set a value to an entity of a map, one need to pass the internalId of the entity in the XML to the entity element. The list of internalIds for each map is provided in Map Entity Specifications section. The table below is the Entity Specification sheet of the World map.

Map Entity Specification Sheet for World Map

The Entities table for the world Map is reproduced below ( from Map Entity Specifications > World & Continents  > World ).

Internal Id Short Name (Abbreviated Name) Long Name
NA NA North America
SA SA South America
EU EU Europe
AS AS Asia
AF AF Africa
AU AU Australia

As you can see above, each entity on the map has three properties:

  • Internal Id (Entity Id) through which we refer to that entity in the XML/JSON data.
  • Short Name of the entity which gets displayed on the map.
  • Full Name of the entity, which by default is shown as tool tip for the entity. You can also opt to show full name on the map instead of short name.

Note: You can get the specification sheet for each map in the Map Entity Specifications section in this documentation.

Note: You can define your own IDs, short names and long names for each entity – we'll see that later.

Let us now look deeper into the XML that we had built in the first sample.

<map borderColor='005879' fillColor='D7F4FF' numberSuffix='Mill.' includeValueInLabels='1' labelSepChar=': ' baseFontSize='9'>
         <data>
            <entity id='NA' value='515' />
            <entity id='SA' value='373' />
            <entity id='AS' value='3875' />
            <entity id='EU' value='727' />
            <entity id='AF' />
            <entity id='AU' value='32' />
         </data>     
</map>

In the above code, we're setting value to the entities of the World map in an XML format that FusionMaps XT can understand.

Each XML data document for FusionMaps XT starts with <map> element. There are a number of cosmetic and functional attributes which you can specify for <map> element. You can see them in XML API page. For this example, we've defined the border color of the map, fill color, number suffix (to be added at the end of every number), a flag to include data values in map labels, the label separator character and font size attributes.

Immediately inside the <map> element, we've defined <data> element, whose child nodes contain the actual data. To define data for each entity on the map, an <entity> element is added as under:

<entity id='NA' value='515' />

The id here corresponds to the internal Id of the entity (picked from "Map Entity Specification" Sheet). value denotes the actual value which we want to show on the map. There are other attributes that you can specify for <entity> element. Please refer to XML API page for the list of attributes.

That completes the XML part of the application.

Using the Visual GUI provided in Download Package > Tools > GUI, you can automatically generate the Entity XML template for any map. That is, you will not have to manually write the <entity> element for each entity of the map. Instead our GUI will build this for you, and you can plug it in your code and then replace the values with values from your data store.

Legend showing colored data Ranges

FusionMaps XT allows you to auto-color each entity based on a defined value-range. Each value range can be defined to have a unique color. This makes the entities distinguishable based on their data. Using color range, you can classify your data into sections, with each section having a different name and specify color to differentiate from each other. For each color range, you'll have to specify the minimum and maximum values, and the hex color code for the range. To display a label for the color range specify the label using the displayValue attribute. The color of the numeric range is specified using the code attribute.

The numeric color range is displayed with their lables in legends. A Legend is a rectangular box appearing at the bottom of the map with icons or a scale along with the labels of the numeric ranges. There are two types of legends. They are:

  1. Icon legend
  2. Gradient legend

As you will find from the sample World map shown above, four Population color ranges are defined for the map. As per the value of the entities/continents, the entities are set with the matched range's color. Also note that since we do not provide value for Africa, no color (from color-range table) is applied to Africa entity. The definition of the color range is as follows:

<map ...>
        ...
   <colorRange>
        <color minValue='1' maxValue='100' displayValue=' Below 100 M' code='F29C9C' />
        <color minValue='100' maxValue='500' displayValue='100 - 500 M' code='F2E0A1' />
        <color minValue='500' maxValue='1000' displayValue='500 - 1000 M' code='649A64' />
        <color minValue='1000' maxValue='5000000000' displayValue='Above 1000 M' code='E1F5C9' />
   </colorRange>
        ...
</map>
 
Please refer to Map XML Sheet page for the list of attributes supported by colorRange element.
 
Marker

Markers are user defined points on the map that help you pin-point cities, junctions, houses, malls, locations etc. You can set a label and tooltip to the marker. You can turn them as hotspots to open a URL, raise an event or call a function. You can set a shape like circle, triangle, diamond, arc or a custom shape/image to the marker. The rule for creating a marker is:

  • define a marker based on the x and y position of the map and
  • make the defined marker visible on the map by applying the marker.

In the map above you can locate a red marker near the top of the North America entity.

Marker shapes
 
You can customize the shapes of a marker by defining custom shapes or loading external images. In the World map above, you will find two custom image marker-shapes are applied as flag of USA and India.
 
Marker connector
 
You can again connect two defined markers on a map using straight lines, which we call marker-connectors. You can show custom labels for the marker connectors, link it to external URLs, show tool tips for the connector and customize all the cosmetics.
 
The XML shown below defines the markers, shapes and connectors for the World map shown above.
<map>
        ...
   <markers>
         <definition>
            <marker id='CA' x='116.65' y='94.85' label='Sales Office' labelPos='top'/>
            <marker id='US' x='131.57' y='153.22' label='Headquarters' labelPos='bottom'/>
            <marker id='IN' x='499.26' y='202.5' label='Accounts'  labelPos='bottom'/>
         </definition>
         <shapes>
            <shape id='USMap' type='image' url='Resources/us_flag.jpg' labelPadding='12' />
            <shape id='INMap' type='image' url='Resources/ind_flag.jpg' labelPadding='12' />
         </shapes>
         <application>
            <marker id='CA' shapeId='circle' toolText='Canada&lt;BR&gt;2 Managers&lt;BR&gt;11 Staff'/>
            <marker id='US' shapeId='USMap' toolText='United States&lt;BR&gt;CEO, CFO, 3 Managers&lt;BR&gt;26 Staff'/>
            <marker id='IN' shapeId='INMap' toolText='India&lt;BR&gt;1 Manager&lt;BR&gt;5 Accountants'/>
         </application>
         <connectors>
            <connector from='CA' to='IN' toolText='remote' dashed='0' thickness='2' color='ff0000' alpha='40'/>
            <connector from='IN' to='US' toolText='direct' dashed='1' thickness='2'  color='0000ff' alpha='90'/>
         </connectors>
    </markers>
        ...
</map>
 
Please refer to Quick Map Configuration > Markers > XML structure page for the list of attributes supported by marker related elements.
 
Next, we'll see how to use the Visual Map Builder for map generation.