AmMap | JavaScript Maps v. 3 | amCharts

Inheritance: AmMap → AmChart

Base class of AmCharts. It can not be instantiated explicitly. It's makeChart method gives you the possibility to create maps easily with a single object.

### Example

    var map = AmCharts.makeChart("mapdiv",{
      "type": "map",
      "dataProvider": {
        "map": "worldHigh",
        ...
      }
    });

### Properties Hide inherited Show inherited

Property | Type | Default | Description
--- | --- | --- | ---
accessible | Boolean | true | When enabled, chart adds aria-label attributes to columns, bullets or map objects. You can control values of these labels using properties like accessibleLabel of AmGraph. Note, not all screen readers support these tags. We tested this mostly with NVDA Screen reader. WAI-ARIA is now official W3 standard, so in future more readers will handle this well. We will be improving accessibility on our charts, so we would be glad to hear your feedback.
accessibleTitle | String |  | <title> element will be added to <svg> node if you set any. It is read by most of the screen readers.
addClassNames | Boolean | false | Specifies, if class names should be added to chart elements.
allLabels | Array[Label] | [] | Array of Labels. Example of label object, with all possible properties: {"x": 20, "y": 20, "text": "this is label", "align": "left", "size": 12, "color": "#CC0000", "alpha": 1, "rotation": 0, "bold": true, "url": "http://www.amcharts.com"}
allowClickOnSelectedObject | Boolean | true | Specifies if user can repeatedly click on already selected object.
allowMultipleDescriptionWindows | Boolean | false | Specifies if multiple description windows at a time are allowed. When set to false, previously opened window is closed when opening a new one.
areasClasses | Object |  | You can create multiple AreasSettings objects and then set them using this property. For example, map.areasClasses["rivers"] = riversSettings; The class "rivers" should be set for your svg areas which should use the riversSettings object.
areasSettings | AreasSettings | AreasSettings | Common settings of areas.
autoDisplay | Boolean | false | If you set it to true the chart will automatically monitor changes of display style of chart’s container (or any of it’s parents) and will render chart correctly if it is changed from none to block. We recommend setting it to true if you change this style at a run time, as it affects performance a bit.
autoResize | Boolean | true | Set this to false if you don't want chart to resize itself whenever its parent container size changes.
autoTransform | Boolean | false | If you set it to true and your chart div (or any of the parent div) has css scale applied, the chart will position mouse at a correct position. Default value is false because this operation consumes some CPU and quite a few people are using css transfroms.
backgroundAlpha | Number | 0 | Opacity of background. Set it to >0 value if you want backgroundColor to work. However we recommend changing div's background-color style for changing background color.
backgroundColor | Color | #FFFFFF | Background color. You should set backgroundAlpha to >0 value in order background to be visible. We recommend setting background color directly on a chart's DIV instead of using this property.
backgroundZoomsToTop | Boolean | false | Specifies if clicking on the "water" zooms to the "top"
balloon | AmBalloon | AmBalloon | The chart creates AmBalloon class itself. If you want to customize balloon, get balloon instance using this property, and then change balloon's properties.
balloonLabelFunction | Function |  | Method which will be called by the map when a balloon with some text is displayed. You can use it to change the default text of a balloon.When this function is called, mapObject and map references are passed to it: balloonLabelFunction(mapObject, ammap); You can extract any data from mapObject and return new balloon text.
borderAlpha | Number | 0 | Opacity of chart's border. Value range is 0 - 1.
borderColor | Color | #000000 | Color of chart's border. You should set borderAlpha >0 in order border to be visible. We recommend setting border color directly on a chart's DIV instead of using this property.
centerMap | Boolean | true | Specifies if the map should be centered.
classNamePrefix | String | amcharts | This prefix is added to all class names which are added to all visual elements of a chart in case addClassNames is set to true.
color | Color | #000000 | Text color.
colorSteps | Number | 5 | If you set values for MapAreas, they are filled with colors between color and colorSolid (both set in AreasSettings). colorSteps property specifies how many different colors should be used. Set this to some big number like 100 if you want each area to be filled with a different shade of color (according to it's value).
creditsPosition | String | top-left | Non-commercial version only. Specifies position of link to amCharts site. Allowed values are: top-left, top-right, bottom-left and bottom-right.
dataLoader | Object |  | A config object for Data Loader plugin. Please refer to the following page for more information.
dataProvider | MapData |  | Data provider of the map.
decimalSeparator | String | . | Decimal separator.
defs | Object |  | Using this property you can add any additional information to SVG, like SVG filters or clip paths. The structure of this object should be identical to XML structure of a object you are adding, only in JSON format.
developerMode | Boolean | false | When developer mode is set to true, you can click anywhere on the map while SHIFT key is pressed to trigger a writeDevInfo event. All the information about current map position/zoom will be transferred to the event handler.
dragMap | Boolean | true | Specifies if the map is draggable.
export | Object |  | Export config. Specifies how export to image/data export/print/annotate menu will look and behave. You can find a lot of examples in amcharts/plugins/export folder. More details can be found here.
fitMapToContainer | Boolean | true | Specifies if the map should be resized to fit to the stage.
fontFamily | String | Verdana | Font family.
fontSize | Number | 11 | Font size.
forceNormalize | Boolean | false | If you set it to true, the map will redraw all the areas, normalizing paths. This might be needed if you use SVG filters with areas. Might not work with maps containing complex paths (with arcs and similar).
handDrawn | Boolean | false | If you set this to true, the lines of the chart will be distorted and will produce hand-drawn effect. Try to adjust chart.handDrawScatter and chart.handDrawThickness properties for a more scattered result.
handDrawScatter | Number | 2 | Defines by how many pixels hand-drawn line (when handDrawn is set to true) will fluctuate.
handDrawThickness | Number | 1 | Defines by how many pixels line thickness will fluctuate (when handDrawn is set to true).
hideBalloonTime | Number | 150 | Time, in milliseconds after which balloon is hidden if the user rolls-out of the object. Might be useful for AmMap to avoid balloon flickering while moving mouse over the areas. Note, this is not duration of fade-out. Duration of fade-out is set in AmBalloon class.
imagesSettings | ImagesSettings | ImagesSettings | Common settings of images.
language | String |  | Allows changing language easily. Note, you should include language js file from amcharts/lang or ammap/lang folder and then use variable name used in this file, like chart.language = "de"; Note, for maps this works differently - you use language only for country names, as there are no other strings in the maps application.
legend | AmLegend |  | Legend of a chart.
legendDiv | String |  | Read-only. Reference to the div of the legend.
linesAboveImages | Boolean | true | You can specify whether lines should be above or below images.
linesSettings | LinesSettings | LinesSettings | Common settings of lines.
listeners | Array[Object] |  | You can add listeners of events using this property. Example: listeners = [{"event":"dataUpdated", "method":handleEvent}];
mapVar | Variable |  |
maxValue | Number |  | Use this property in case you set values for your areas and wish to set a different maxValue. These values are used when choosing a color for an area.
minValue | Number | 0 | Use this property in case you set values for your areas and wish to set a different minValue (it's 0 by default). These values are used when choosing a color for an area.
mouseWheelZoomEnabled | Boolean | false | Specifies if zooming with mouse wheel is enabled.
panEventsEnabled | Boolean | true | This setting affects touch-screen devices only. If a chart is on a page, and panEventsEnabled are set to true, the page won't move if the user touches the chart first. If a chart is big enough and occupies all the screen of your touch device, the user won’t be able to move the page at all. If you think that selecting/panning the chart or moving/pinching the map is a primary purpose of your users, you should set panEventsEnabled to true, otherwise - false.
path | String | ammap/ | Specifies absolute or relative path to amCharts files, i.e. "ammap/". (where all .js files are located) If relative URLs are used, they will be relative to the current web page, displaying the chart. You can also set path globally, using global JavaScript variable AmCharts_path. If this variable is set, and "path" is not set in map config, the mapwill assume the path from the global variable. This allows setting amCharts path globally. I.e.:
    var AmCharts_path = "/libs/ammap/";
"path" parameter will be used by the maps to locate it's files, like images, plugins or patterns.
pathToImages | String |  | Specifies path to the folder where images like resize grips, lens and similar are. IMPORTANT: Since V3.14.12, you should use "path" to point to amCharts directory instead. The "pathToImages" will be automatically set and does not need to be in the chart config, unless you keep your images separately from other amCharts files.
percentPrecision | Number | 2 | Precision of percent values. -1 means percent values won't be rounded at all and show as they are.
precision | Number | -1 | Precision of values. -1 means values won't be rounded at all and show as they are.
prefixesOfBigNumbers | Array[Object] | [{"number":1e+3,"prefix":"k"},{"number":1e+6,"prefix":"M"},{"number":1e+9,"prefix":"G"},{"number":1e+12,"prefix":"T"},{"number":1e+15,"prefix":"P"},{"number":1e+18,"prefix":"E"},{"number":1e+21,"prefix":"Z"},{"number":1e+24,"prefix":"Y"}] | Prefixes which are used to make big numbers shorter: 2M instead of 2000000, etc. Prefixes are used on value axes and in the legend. To enable prefixes, set usePrefixes property to true.
prefixesOfSmallNumbers | Array[Object] | [{"number":1e-24, "prefix":"y"},{"number":1e-21, "prefix":"z"},{"number":1e-18, "prefix":"a"},{"number":1e-15, "prefix":"f"},{"number":1e-12, "prefix":"p"},{"number":1e-9, "prefix":"n"},{"number":1e-6, "prefix":"μ"},{"number":1e-3, "prefix":"m"}] | Prefixes which are used to make small numbers shorter: 2μ instead of 0.000002, etc. Prefixes are used on value axes and in the legend. To enable prefixes, set usePrefixes property to true.
preventDragOut | Boolean | false | If set to true, user won't be able to drag map out of the visible area.
processCount | Number | 1000 | If processTimeout is > 0, 1000 data items will be parsed at a time, then the chart will make pause and continue parsing data until it finishes.
processTimeout | Number | 0 | If you set it to 1 millisecond or some bigger value, chart will be built in chunks instead of all at once. This is useful if you work with a lot of data and the initial build of the chart takes a lot of time, which freezes the whole web application by not allowing other processes to do their job while the chart is busy.
projection | String | mercator | Projection of the map. Projection can be also set in SVG map - all svg maps which are distributed with amMap have projection set in SVG. Available values are: "winkel3", "eckert3", "eckert5", "eckert6", "miller", "equirectangular" and "mercator" (default).
responsive | Object |  | A config object for Responsive plugin. Please refer to the following page for more information.
selectedObject | MapObject |  | Read-only. Returns currently selected map object. Use map.selectObject(mapObject) method to change it.
showAreasInList | Boolean | true | Specifies if MapAreas should be displayed in the ObjectList.
showBalloonOnSelectedObject | Boolean | true | Specifies if balloon should be displayed when hovering currently seleced object.
showDescriptionOnHover | Boolean | false | Specifies if description window should be shown when user hovers over the object.
showImagesInList | Boolean | false | Specifies if MapImages should be displayed in the ObjectList.
showLinesInList | Boolean | false | Specifies if MapLines should be displayed in the ObjectList.
showObjectsAfterZoom | Boolean | false | Specifies if child objects should be added to stage only after the map zoomed to the final position.
smallMap | SmallMap |  | Small map displays a small map indicating zoom level and position.
svgIcons | Boolean | true | Charts will use SVG icons (some are loaded from images folder and some are drawn inline) if browser supports SVG. his makes icons look good on retina displays on all resolutions.
tapToActivate | Boolean | true | Charts which require gestures like swipe (charts with scrollbar/cursor) or pinch (maps) used to prevent regular page scrolling and could result page to stick to the same spot if the chart occupied whole screen. Now, in order these gestures to start working user has to touch the chart/maps once. Regular touch events like touching on the bar/slice/map area do not require the first tap and will show balloons and perform other tasks as usual. If you have a map or chart which occupies full screen and your page does not require scrolling, set tapToActivate to false – this will bring old behavior back.
theme | String | none | Theme of a chart. Config files of themes can be found in amcharts/themes/ folder. More info about using themes.
thousandsSeparator | String | , | Thousands separator.
titles | Array[Title] | [] | Array of Title objects.
touchClickDuration | Number | 0 | If you set it to 200 (milliseconds) or so, the chart will fire clickGraphItem or clickSlice (AmSlicedChart) or clickMapObject only if user holds his/her finger for 0.2 seconds (200 ms) on the column/bullet/slice/map object.
type | String |  | Type of a chart. Required when creating chart using JSON. Possible types are: serial, pie, xy, radar, funnel, gauge, map, stock.
useHandCursorOnClickableOjects | Boolean | true | pecifies if hand cursor should be displayed when mouse moves over a clickable object.
useObjectColorForBalloon | Boolean | true | Specifies if balloon should use color of currenlty hovered object.
usePrefixes | Boolean | false | If true, prefixes will be used for big and small numbers. You can set arrays of prefixes via prefixesOfSmallNumbers and prefixesOfBigNumbers properties.
valueLegend | ValueLegend |  | Value legend displays a color range used by areas (in case you set values for your areas).
version | String |  | Read-only. Indicates current version of a script.
zoomControl | ZoomControl | ZoomControl | Zoom control of the map.
zoomDuration | Number | 1 | Duration of zoom animation, in seconds.
zoomOnDoubleClick | Boolean | true | Specifies if the map should be zoomed-in when user double clicks anywhere on the map (except objects which are clickable).

### Methods Hide inherited Show inherited

Name | Parameters | Returns | Description
--- | --- | --- | ---
addLabel(x, y, text, align, size, color, rotation, alpha, bold, url) | x - horizontal coordinate y - vertical coordinate text - label's text align - alignment (left/right/center) size - text size color - text color rotation - angle of rotation alpha - label alpha bold - specifies if text is bold (true/false), url - url of a |  | Adds a label on a chart. You can use it for labeling axes, adding chart title, etc. x and y coordinates can be set in number, percent, or a number with ! in front of it - coordinate will be calculated from right or bottom instead of left or top.
addLegend(legend, legendDivID) | legend - AmLegend, legendDivID - id or reference to legend div (optional) |  | Adds a legend to the chart. By default, you don't need to create div for your legend, however if you want it to be positioned in some different way, you can create div anywhere you want and pass id or reference to your div as a second parameter. (NOTE: This method will not work on StockPanel.)
addListener(type, handler) | type - string like 'dataUpdated' (should be listed in 'events' section of this class or classes which extend this class). handler - function which is called when event happens |  | Adds event listener to the object.
addTitle(text, size, color, alpha, bold) | text - text of a title size - font size color - title color alpha - title opacity bold - boolean value indicating if title should be bold. |  | Adds title to the top of the chart. Pie, Radar positions are updated so that they won't overlap. Plot area of Serial/XY chart is also updated unless autoMargins property is set to false. You can add any number of titles - each of them will be placed in a new line. To remove titles, simply clear titles array: chart.titles = []; and call chart.validateNow() method.
checkIfSelected(mapObject) |  | Boolean | Checks if the object is currently selected. In case map object is linked with currently selected map object, this method will return true.
clear() |  |  | Clears the chart area, intervals, etc.
clearLabels() |  |  | Removes all labels added to the chart.
clearMap() |  |  | Removes the map and all objects from container.
clickMapObject(mapObject) |  |  | Simulates click on a map object - sets a new selectedObject and fires event.
closeAllDescriptions |  |  | Closes all open description windows.
coordinatesToStageXY(longitude, latitude) | latitude and longitude | {x:x, y:y} | x and y are coordinates of the chart div, in pixels.
coordinatesToXY(longitude, latitude) | latitude and longitude | {x:x, y:y} | x and y are coordinates of the map, in pixels.
coordinateToLatitude(coordinate) |  | latitude | Converts provided map y coordinate to latitude.
coordinateToLongitude(coordinate) |  |  | Converts provided map x coordinate to longitude.
getAreaCenterLatitude(mapArea) |  | latitude | Returns latitude of the area center.
getAreaCenterLongitude(mapArea) |  | longitude | Returns longitude of the area center.
getDevInfo() |  | Object | Returns object with information about the current mouse position: {type:"writeDevInfo", chart:AmMap, zoomLevel:zoomLevel, zoomX:zoomX, zoomY:zoomY, zoomLatitude:zoomLatitude, zoomLongitude:zoomLongitude, latitude:latitude, longitude:longitude, left:left, top:top, right:right, bottom:bottom, percentLeft:percentLeft, percentTop:percentTop, percentRight:percentRight, percentBottom:percentBottom, str:string}
getObjectById(id) | id - id of an object | MapObject | Returns MapObject by a given id.
hideGroup(groupId) |  |  | Hides objects with provided group id
invalidateSize() |  |  | Use this method to force the chart to resize to it's current container size.
kilometersToPixels(kilometers) |  | pixels | Converts kilometers to pixels. Note, if the map size changes, this will also change.
latitudeToCoordinate(latitude) |  | y coordinate | *deprecated, use coordinatesToXY method instead. Converts provided latitude to y coordinate of the map.
latitudeToY(latitude) | latitude | Number | *deprecated, use coordinatesToStageXY method instead. Converts provided latitude to stage's x coordinate.
longitudeToCoordinate(longitude) |  | x coordinate | *deprecated, use coordinatesToXY method instead. Converts provided longitude to x coordinate of the map.
longitudeToX(longitude) | longitude | Number | *deprecated, use coordinatesToStageXY method instead. Converts provided longitude to stage's x coordinate.
makeChart(container, config, delay) | container - id of a DIV or reference of the container element - config contains the whole setup for the chart - delay in milliseconds to delay the initiation of the chart | chart instance | This method allows to create charts with a single config.
milesToPixels(miles) |  | pixels | Converts miles to pixels. Note, if the map size changes, this will also change.
moveDown() |  |  | Moves map down by panStepSize (property of ZoomControl)
moveLeft() |  |  | Moves map left by panStepSize (property of ZoomControl).
moveRight() |  |  | Moves map right by panStepSize (property of ZoomControl).
moveUp() |  |  | Moves map up by panStepSize (property of ZoomControl).
removeLegend() |  |  | Removes chart's legend.
removeListener(chart, type, handler) | chart - chart object, type - event name, handler - method |  | Removes event listener from chart object.
returnInitialColor(mapObject) | mapObject |  | Returns initial color for map object.
rollOutMapObject(mapObject) |  |  | Simulates a roll-out off a map object. Usefull when you want to highlight some area or image from other control.
rollOverMapObject(mapObject) |  |  | Simulates a roll-over of a map object. Usefull when you want to highlight some area or image from other control.
selectObject(mapObject) | mapObject |  | Selects map object - MapArea, MapImage, MapLine or MapData. If you want to return map to initial view, use map.selectObject() - with no MapObject set - this will select current dataProvider.
showGroup(groupId) |  |  | Shows objects with provided group id.
stageXYToCoordinates(x, y) | x an y, are coordinates of chart div, in pixels |  | Returns longitude and latitude of the map point.
validateData() |  |  | This method should be called after data in your data provider changed or a new array was set to dataProvider. After calling this method the chart will parse data and redraw.
validateNow(validateData, skipEvents) |  |  | This method should be called after you changed one or more properties of any class. The chart will redraw after this method is called.Both attributes, validateData and skipEvents are optional (false by default).
write(container) | container - id of a DIV or DIV object which will hold the chart |  | Adds chart to the specified DIV.
xyToCoordinates(x, y) | x an y, are coordinates of the map, in pixels | {longitude:longitude, latitude:latitude} | Returns longitude and latitude of the map point.
zoomIn() |  |  | Zooms in. Current zoomLevel is multiplied by zoomFactor (property of ZoomControl).
zoomLatitude() |  | latitude | Returns current latitude of the point which is at the center of the map container.
zoomLevel() |  | zoom level | Returns current zoom level.
zoomLongitude() |  | longitude | Returns current longitude of the point which is at the center of the map container.
zoomOut() |  |  | Zooms out. Current zoomLevel is divided by zoomFactor (property of ZoomControl).
zoomTo(zoomLevel, zoomX, zoomY, instantly) |  |  | Zooms the map to provided zoom level and coordinates.
zoomToGroup(group) |  |  | Zooms-in the map to so that all objects of a group would fit into AmMap container.Works only with grouped MapAreas, doesn't work with MapImages. The group property is an id of the group. Or you can pass array of areas (not necessary grouped).
zoomToLongLat(zoomLevel, longitude, latitude, instantly) |  |  | Zooms in the map and places provided latitude and longitude in the center of a component container.
zoomToMapXY(zoomLevel, x, y, instantly) |  |  | Zooms the map to provided coordinates.
zoomToSelectedObject(mapObject) |  |  | Zooms to currently selected object.
zoomX() |  | zoom x | Returns current zoom x coordinate
zoomY() |  | zoom y | Returns current zoom y coordinate.

### Events Hide inherited Show inherited

Name | Event object | Description
--- | --- | ---
animationFinished | {type:"animationFinished", chart:AmChart} | Dispatched when initial chart animations are finished.
buildStarted | {type:"buildStarted", chart:AmChart} | Fired just before the chart starts to build itself for the first time. Note: you might need to set processTimeout to > 0 value in order to register this event properly.
click | {type:'click', chart:AmMap} | Fired everytime user clicks on a map, except if the map was dragged or zoomed-in with zoomControl. By using this event and getDevInfo method you can build your custom map editing user interface.
clickMapObject | {type:"clickMapObject", mapObject:MapObject, chart:AmMap, event:MouseEvent} | Dispatched when user clicks on a map object.
dataUpdated | {type:"dataUpdated", chart:AmChart} | Dispatched when chart is build for the first time or after validateData() method was called.
descriptionClosed | {type:"descriptionClosed", chart:AmMap} | Fired when user closes description window.
dragCompleted | {type:"dragCompleted", zoomX:zoomX, zoomY:zoomY, zoomLevel:zoomLevel, chart:AmMap} | Dispatched every time when user finishes dragging the map.
drawn | {type:"drawn", chart:AmChart} | Fired every time chart is drawn or re-drawn - graph toggle, chart area resize, etc. Please note, that this event will not fire on zoom. Use "zoomed" event instead to catch those events.
homeButtonClicked | {type:"homeButtonClicked", chart:AmMap} | Dispatched when home icon of the ZoomControl is clicked
init | {type:"init", chart:AmChart} | Dispatched when chart is build for the first time.
mouseDownMapObject | {type:"mouseDownMapObject", mapObject:MapObject, chart:AmMap, event:MouseEvent} | Dispatched when user presses down mouse button.
positionChanged | {type:"positionChanged", zoomX:zoomX, zoomY:zoomY, zoomLevel:zoomLevel, chart:AmMap} | Dispatched every time when map position is changed or map is zoomed.
rendered | {type:"rendered", chart:AmChart} | Dispatched when the chart is build for the first time and each time after chart.validateNow() method is called and the chart is build.
rollOutMapObject | {type:"rollOverMapObject", mapObject:MapObject, chart:AmMap, event:MouseEvent} | Dispatched when user rolls-out of a map object.
rollOverMapObject | {type:"rollOverMapObject", mapObject:MapObject, chart:AmMap, event:MouseEvent} | Dispatched when user rolls-over a map object.
selectedObjectChanged | {type:'selectedObjectChanged', chart:AmMap} | Dispatched when selected object changes.
writeDevInfo | {type:"writeDevInfo", chart:AmMap, zoomLevel:zoomLevel, zoomX:zoomX, zoomY:zoomY, zoomLatitude:zoomLatitude, zoomLongitude:zoomLongitude, latitude:latitude, longitude:longitude, left:left, top:top, right:right, bottom:bottom, percentLeft:percentLeft, percentTop:percentTop, percentRight:percentRight, percentBottom:percentBottom, str:string} | Dispatched when map.developerMode is set to true and user holds shift and clicks left mouse button. Use this to get zoom level and coordinates of clicked place.
zoomCompleted | {type:'zoomCompleted', chart:AmMap} | Dispatched when zooming is completed.