JavaScript API | Documentation

Note, there are major changes to the API starting with version 3.0. More info.

Because our HTML5 maps are built using JavaScript and SVG, it is possible to manipulate the map in real time using JavaScript. We have put together an API to make it easy to communicate with our map by calling JavaScript functions. The API makes it possible for the map to communicate and interact with other elements on the page.

Standard Framework

  1. Edit the properties of the map

    Edit the simplemaps_worldmap_mapdata object using JavaScript. For example:

    • To change the width of the map:

    • To change the color of a state:

    • To change the description of a location:


  2. Update the map with one of two functions

    • simplemaps_worldmap.load()

      Load or reload the map. This will create or recreate the map. Slower.

    • simplemaps_worldmap.refresh()
      Refresh the map. This updates the map properties (colors etc.) but does not redraw the map. Very fast.


It's possible to use JavaScript to zoom around the map.

simplemaps_worldmap.state_zoom(state_id, callback)
Zoom the map to a state by id. callback is optional.
simplemaps_worldmap.region_zoom(region_id, callback)
Zoom the map to a region by id. callback is optional.
simplemaps_worldmap.location_zoom(location_id, zoom_percentage, callback)
Zoom the map to a location by id. callback is optional.
zoom_percentage is the size of the viewbox relative to location size (4 by default).
Requires: main_settings.manual_zoom: "yes",.
Zooms out. Equivalent to clicking the back arrow in the map. callback is optional.
Tells you the current zoom level of the map. ('out', 'region', 'state')

Zoom examples

simplemaps_worldmap.state_zoom("ID"); //Zoom to state by id
simplemaps_worldmap.region_zoom("0"); //Zoom to region by id
simplemaps_worldmap.region_zoom("0", function(){ alert("Zoom done")} ); //Zoom and callback when complete
simplemaps_worldmap.location_zoom('0', '4');

Trigger Popups

simplemaps_worldmap.popup(type, id) Open a popup/tooltip programmatically. Type can be ['location', 'state', 'region']. Example: simplemaps_worldmap.popup('location', '0')
simplemaps_worldmap.popup_hide() Hides any open popup

Map Instances (example)

simplemaps_worldmap.create() create a new map instance from the global simplemaps_worldmap_mapdata object. Example: var map1=simplemaps_worldmap.create();
simplemaps_worldmap.copy() copies an existing map instance. Example: var map2=map1.copy();
map_instance.mapdata mapdata is bound to each map instance. Example: map1.mapdata.main_settings.state_color='red';
map_instance.mapinfo mapinfo is bound to each map instance. Example: map1.mapinfo.initial_view=150;


simplemaps_worldmap.refresh_state(id) Allows you to refresh a single state by id to more efficiently update the map.
simplemaps_worldmap.get_xy() Allows you to click on the map to get any point's x and y coordinates. Useful for labels.
simplemaps_worldmap.calibrate() Provides an object containing the bounding box for every state. Helps with performance if you use this to update mapinfo.state_bbox_array after changing state paths.
simplemaps_worldmap.zoom_level A string that contains the current zoom level ['out', 'region', 'state', 'manual']
simplemaps_worldmap.zoom_level_id If simplemaps_worldmap.zoom_level is 'region' or 'state' this contains the relevant id. false otherwise.
simplemaps_worldmap.proj(lat, lng) This function will convert latitude and longitude into x,y coordinates using the map's projection. Returns {'x': x, 'y': y}
simplemaps_worldmap.pulse(id) Pulse a location by id.
simplemaps_worldmap.pulse_state(id) Pulse a state by id.
simplemaps_worldmap.mobile_device true if the device is a mobile device. Created when the worldmap.js script is embedded.

Home | License | Privacy | Releases | Testimonials | Resources | Documentation | Order Lookup | All Maps | FAQs
Formerly and is a product of Pareto Software, LLC. © 2010-2024.