Developer Guide

Getting Started

The ALK Maps Javascript API enables you to embed ALK's commercial maps and routing in your own web applications. This guide is intended to get you started, and give you an overview of the main functionality. It is designed for people familiar with JavaScript programming and object-oriented programming concepts. For more detailed reference of all the functions, see the ALK Maps API Documentation

A Basic Map

The easiest way to learn about ALK Maps is to see a basic example. This code will produce a map centered on the lower 48 states of the U.S.

<!DOCTYPE html>
<html>
  <head>
	<style type="text/css">
	  html, body, #map {
		margin: 0;
		padding: 0;
		height: 100%;
	  }
	</style>
	<script src="https://maps.alk.com/api/1.2/alkmaps.js" type="text/javascript"></script>
	<script type="text/javascript">
	  var map;
	  var lon = -96, lat = 35, zoom = 3;
	
	  function init() {
		ALKMaps.APIKey = "YOUR_KEY_HERE";
		
		map = new ALKMaps.Map('map');

		var lonLat = new ALKMaps.LonLat(lon, lat).transform(new ALKMaps.Projection("EPSG:4326"), map.getProjectionObject());
		map.setCenter(lonLat, zoom);
	  }
	</script>
  </head>
  <body onLoad="init()">
	<div id="map" style="width:100%; height:100%">
	</div>
  </body>
</html>

Default Controls

Default Map Controls

By default, the map comes with several controls enabled by default. These controls allow the user to pan and zoom via the mouse and keyboard. A scale control is also drawn in the lower right-hand corner of the map to provide a visual indication of the current scale of the map.

Please note that by default, all map controls will inherit their projection from the map. For example, a mouse position control on a map in spherical mercator will display its coordinates in meters rather than degrees. You change this by setting the displayProjection parameter of the map to the desired projection.

var map = new ALKMaps.Map("map",{ displayProjection: new ALKMaps.Projection("EPSG:4326") });

For more information on what controls are and the different types available, see the Controls section of this guide.

Interactive Samples

Throughout the ALKMaps Developer guide, there will be interactive areas to test out the concepts introduced from within the browser. Below is the interactive version of the code above. You can easily change the zoom level or longitude and latitude. Press the Update button to refresh the map and use the Reset button to return the code to the original state.

var map;
var lon = -96, lat = 35, zoom = 3;

//ALKMaps.APIKey = "YOUR_KEY_HERE";
		
map = new ALKMaps.Map("map");
	
var lonLat = new ALKMaps.LonLat(lon, lat).transform(new ALKMaps.Projection("EPSG:4326"), map.getProjectionObject());
map.setCenter(lonLat, zoom);

Breaking down the elements

We recommend declaring the document type as HTML5 using <!DOCTYPE html> which will make your document much more cross-browser compliant. The DOCTYPE will be ignored by some older browsers, but it won't cause them to fail. In order to account for quirks in these older browsers we must also explicitly set the height of the HTML and BODY elements as well as our map container.

The Toolkit

You must include a script tag reference to the ALK Maps toolkit JavaScript file in HTML.

<script src="https://maps.alk.com/api/1.2/alkmaps.js" type="text/javascript"></script>

The API Key

In order for the toolkit to work properly, you declare a variable containing your API key before calling any objects in the toolkit.

ALKMaps.APIKey = "YOUR_KEY_HERE";

In version 1.2 you also have the option of being able to specify your API key in the query string of the ALKMaps.js reference.

<script src="https://maps.alk.com/api/1.2/alkmaps.js?key=YourAPIKeyHere" type="text/javascript"></script>

The Map

The first element needed is the map. The map is created by creating a new instance of ALKMaps.Map and passing in the DOM id of the container that will hold the map.

map = new ALKMaps.Map('map');

The HTML element that will serve as the map container needs to have an explicit width and height set via CSS either in an associated stylesheet or inline on the element. These values can either be percentages or absolute values and can be changed at anytime in the page lifecycle. Due to way browsers report sizing, using only min-width and min-height will cause the map to not render properly.

The Center

Once the map is created, you'll need to set the center and zoom level of the map. This is required so the map knows what area to draw.

var center = new ALKMaps.LonLat(-96, 35).transform(new ALKMaps.Projection("EPSG:4326"), map.getProjectionObject());
map.setCenter(center, 3);