Developer Guide

Rail Routing

Routing is done using ALK Maps Data. The display of rail routes is handled through the Rail Routing Layer.

Routing Layer

The first step in generating routes is to add a routing layer to your map. The routing layer will be responsible for both retrieving and drawing the routes based on the stops and properties you define.

var routingLayer = new ALKMaps.Layer.RailRouting( "Rail Route Layer" );
myMap.addLayer(routingLayer);

Add Route

Once you have a routing layer added to your map, the next step is to add routes. To generate a route you will need at least two stops (an origin and a destination).

The addRoute method of the routing layer takes up to four parameters for creating a route: stops, functionOptions, and routeOptions.

//ALKMaps.APIKey = "YOUR_KEY_HERE";
		
var map = new ALKMaps.Map("map");
var layer = new ALKMaps.Layer.BaseMap( "ALK Maps", {}, {displayInLayerSwitcher: false});
map.addLayer(layer);
					
map.setCenter();
					
var routingLayer = new ALKMaps.Layer.RailRouting( "Rail Route Layer" );
map.addLayer(routingLayer);
var stops = [
  {
      "format": "StationState",
      "name": "Denver CO",
      "railroad": "UP"
  },
  {
      "format": "StationState",
      "name": "Oakland CA",
      "railroad": "UP"
  }];
routingLayer.addRoute({
	stops: stops,
	functionOptions:{
		routeId: "DenverToOaklandCA"
	},
	routeOptions: {
		routingPreference: "Practical",
		distUnit: "Miles"
	},
	reportOptions: {}
});

Station Stops

The stops parameter of the addRoute method should contain an array of Objects representing the stations of the route.

Parameter	Type	Description
`format`	`[1\|2\|3\|4\|5]`	Station format type 1 - SPLC 9-digit numeric Standard Point Location Code 2 - FSAC 5-digit numeric Freight Station Account Code 3 - StationState Station name and State abbreviation 4 - ERPC ERPC or 3-3-3 alpha code and State abbreviation - separated by a space or a comma 5 - Rule 260 Junction Code 5-character alpha code for Junctions
`name`	`string`	Station name or code The following is a list of acceptable format specific to each StationFormat: StationState: Full station name and state abbreviation separated by a space or comma. FSAC: Full 5 digit FSAC SPLC: Full 9 digit SPLC ERPC: ERPC code also called 3-3-3 and state abbreviation separated by a space or comma. R260: 5-character alpha code
`railroad`	`string`	2 to 4 character Standard Carrier Alpha Code.

Function Options

The functionOptions parameter contains options related to the functionality of the route.

Parameter	Type	Description
`routeId`	`string`	A unique string values used to identify a route. It is needed when removing or updating a route.
`async`	`boolean`	Default: true Determine whether the route request will be asynchronous. If so, a callback function can be specified. If a type of web browser, like IE, uses XDomainRequest to issue HTTP request, it is required to make asynchronous calls due to limitations of the browser.
`success`	`function`	Function to be called on the success of the asynchronous routing request.
`failure`	`function`	Function to be called when error happens.
`style`	`ALKMaps.StyleMap`	`{strokeColor: "#00C000", strokeOpacity: 0.6}` Currently, `strokeOpacity` and `strokeColor` are the supported styling options. Note: See Route Colors for more information.
`frameRoute`	`boolean`	Default: true Indicates whether the center point and zoom level of the map will be adjusted to show the route in full frame.
`showHandles`	`boolean`	Default: true Indicates whether to show the origin/waypoint/destination graphics.

Route Options

The routeOptions parameter contains options related to the generation of the route and optional reports.

Parameter	Type/Values	Description
`routingPreference`	`[Practical\|Intermodal\|Shortest\| CoalBulk\|AutoRacks\|FuelSurcharge]`	Default is FuelSurcharge. Routing preference for route calculation. Practical routing is the optimal for general merchandise traffic. Intermodal routing is specific to intermodal trains. Only locations with intermodal service can be entered as origin/destinations. Shortest routing will route to the shortest path. Coal/Bulk Routing is specific to Coal/Bulk unit trains. AutoRack routing is specific to multi-levels. Fuel Surcharge routing is practical or shortest routing depending on the railroad.
`distUnit`	`[Miles\|Kilometers]`	Default: Miles Units for distances included in the report.

Remove Route

You can remove individual routes in a particular routing layer by calling the removeRoute method with the routeId of the route you would like to remove.

routingLayer.removeRoute("myRoute");

Set Route Visibility

You can set the visibility of individual routes in a particular routing layer by calling the setRouteVisibility method with the routeId of the route as the first parameter and a boolean indicating whether or not the route should be visibile as the second. True indicates that the route should be shown, and false indicates that the route should be hidden.

routingLayer.setRouteVisibility("myRoute", false); //hides the route

Route Handles

The route handles (icons displayed at the origin, destination, and waypoints) can be shown/hidden or changed.

Visibility

The visibility of route handles can be set when the route is added via the showHandles option in the functionOptions of the addRoute call.

routingLayer.addRoute({
	
	...

	functionOptions:{
		routeId: "DenverToOaklandCA", 
		showHandles: false
	},
	
	...

});

The visibility can also be changed after the route has been created via a call to the setRouteHandleVisibility on the routing layer. The function takes the routeId and a boolean value indicating the visibility as parameters.

routingLayer.setRouteHandleVisibility("DenverToOaklandCA", false);

Graphics

In addition to being hidden, the route handle graphics can be changed via the setRouteHandle function on the routing layer or by using the externalImages parameter of addRoute. Changes to the route handle graphics only affect handles that are currently part of the route. Handles added after the graphic change will need to be set after they are added.

routingLayer.setRouteHandle(
	"MyRoute", 
	"O",
	{
		externalGraphic: "https://maps.alk.com/api/1.2/img/fav.png"
	}
);

The only field of the externalImages object is images, an array of image locations that at each index matches up to the corresponding element of the stops array. To use the ALKMaps default image for only certain handles, simply place null at that index of the images array.

//ALKMaps.APIKey = "YOUR_KEY_HERE";

var map = new ALKMaps.Map("map");
var layer = new ALKMaps.Layer.BaseMap( "ALK Maps", {}, {displayInLayerSwitcher: false});
map.addLayer(layer);

map.setCenter();

var routingLayer = new ALKMaps.Layer.RailRouting( "Rail Route Layer");
map.addLayer(routingLayer);
var stops = [
  {
      "format": "StationState",
      "name": "Denver CO",
      "railroad": "UP"
  },
  {
      "format": "StationState",
      "name": "Oakland CA",
      "railroad": "UP"
  }];
routingLayer.addRoute({
	stops: stops,
    externalImages: 
        {
            images: [ null, ALKMaps.IMAGE.COMMUTER_RAIL ] //use null if you do not want to set the image for a stop at the corresponding index.
        },
	functionOptions:{
		routeId: "DenverToOaklandCA",
		success: function(){
			routingLayer.setRouteHandle(
				"DenverToOaklandCA", 
				"O",
				{
					externalGraphic: "https://maps.alk.com/api/1.2/img/fav.png"
				}
			);
		},
		failure: function(response){
			// handles error here
		}
	},
	routeOptions: {}
});

The first parameter of setRouteHandle is the routeId of the route containing the handle to change.

The second parameter indicate which handle to change. This can be specified by either the type or index of the point. Valid types are "O" for origin, "D" for destination, or "W" for waypoint, or "A" for all types. If the route contains several stop/waypoints, all graphics will be updated. In addition to types, you may also specify the index to select the handle. The index is zero-based starting at the origin.

The third parameter is an object representing the style properties to be set. Valid style properties are:

Property	Description
`externalGraphic`	The URL of the image to be used as the handle.
`graphicWidth`	The width of the image.
`graphicHeight`	The height of the image.
`graphicXOffset`	The X offset from the stop point.
`graphicYOffset`	The Y offset from the stop point.

Graphic Defaults

In version 1.2 there is the option of setting the default graphic used for each handle type. This means that if the neither the setRouteHandle function is called or the externalImages paramater of addRoute is not specified for a given stop, you can choose the image that will be used instead for origins, waypoints, and destinations by default.

To set the default images for the origin, waypoint, and destination handles when declaring your routing layer, you must specify the image location for the originURL, waypointURL, and destinationURL parameters respectively.

//ALKMaps.APIKey = "YOUR_KEY_HERE";
		
var map = new ALKMaps.Map("map");
var layer = new ALKMaps.Layer.BaseMap( "ALK Maps", {}, {displayInLayerSwitcher: false});
map.addLayer(layer);
					
map.setCenter();
					
var routingLayer = new ALKMaps.Layer.RailRouting( "Rail Route Layer" , {
    originURL: ALKMaps.IMAGE.TRAIN_STATION,
    waypointURL: ALKMaps.IMAGE.TRAIN_STATION,
    destinationURL:ALKMaps.IMAGE.TRAIN_STATION
});
map.addLayer(routingLayer);

var stops = [
  {
      "format": "StationState",
      "name": "Denver CO",
      "railroad": "UP"
  },
  {
      "format": "StationState",
      "name": "Oakland CA",
      "railroad": "UP"
  },
  {
    "Format": "StationState",
    "Name": "Los angeles ca",
    "Railroad": "BNSF"
  }];
routingLayer.addRoute({
	stops: stops,
	functionOptions:{
		routeId: "DenverToOaklandCA",
	},
	routeOptions: {},
	reportOptions: {}
});

SVG

You now have the ability to specify custom SVG content to render your route handles using the handleSvg property of the functionOptions parameter of addRoute. The available properties of the handleSvg object are explained in the table below.

Property	Type	Description
`content`	`String`	A string containing an SVG element.
`size`	`ALKMaps.Size`	Size of the SVG element. The default size is the bounding box of the element.
`offset`	`ALKMaps.Pixel`	The offset of the SVG element. Default `ALKMaps.Pixel(width/2, height/2)`

//ALKMaps.APIKey = "YOUR_KEY_HERE";
		
var map = new ALKMaps.Map("map");
var layer = new ALKMaps.Layer.BaseMap( "ALK Maps", {}, {displayInLayerSwitcher: false});
map.addLayer(layer);
					
map.setCenter();
                        
var svgContent = '<svg xmlns="http://www.w3.org/2000/svg" >' +
    '<circle id="svgCircle" stroke="black" fill="yellow" cx="12" cy="12" r="12" />' +
    '<text id="svgText" x="12" y="12" font-size="10pt" font-family="arial" font-weight="bold" text-anchor="middle" fill="black" transform = "rotate(90 10 11)">: )</text>' +
    '</svg>';
					
var routingLayer = new ALKMaps.Layer.RailRouting( "Rail Route Layer" );
map.addLayer(routingLayer);
var stops = [
  {
      "format": "StationState",
      "name": "Denver CO",
      "railroad": "UP"
  },
  {
      "format": "StationState",
      "name": "Oakland CA",
      "railroad": "UP"
  }];		
routingLayer.addRoute({
	stops: stops,
	functionOptions:{
		routeId: "DenverToOaklandCA",
		handleSvg: {
            content: svgContent,
            size: new ALKMaps.Size(26, 26)                
        }
	},
	routeOptions: {},
	reportOptions: {}
});

Route Colors

Different route colors are generated by the toolkit for each new route created. If you would like to specify a particular color for a route, you can pass in the color as a style object when the route is created.

routingLayer.addRoute({
	
	...

	functionOptions:{
		routeId: "DenverToOaklandCA", 
		style: {
			strokeOpacity: 0.9,
			strokeColor: "#0000FF"
		}
	},
	
	...

});

Currently, strokeOpacity, strokeColor, strokeLinecap, strokeWidthand strokeDashstyle are the supported styling options. Stroke opacity value ranges are from 0 to 1. Stroke color takes hex code in string, like "#ee9900". Valid value for line cap is "butt", "round", or "square". Valid value for dash style is "dot", "dash", "dashdot", "longdash", "longdashdot" or "solid" and most SLD patterns will render correctly. If stroke width is supplied, default width in the context will be replaced.

//ALKMaps.APIKey = "YOUR_KEY_HERE";
		
var map = new ALKMaps.Map("map");
var layer = new ALKMaps.Layer.BaseMap( "ALK Maps", {}, {displayInLayerSwitcher: false});
map.addLayer(layer);
					
map.setCenter();
					
var routingLayer = new ALKMaps.Layer.RailRouting( "Rail Route Layer" );
map.addLayer(routingLayer);
var stops = [
  {
      "format": "StationState",
      "name": "Denver CO",
      "railroad": "UP"
  },
  {
      "format": "StationState",
      "name": "Oakland CA",
      "railroad": "UP"
  }];			
routingLayer.addRoute({
	stops: stops,
	functionOptions:{
		routeId: "DenverToOaklandCA",
		style: {
			strokeOpacity: 0.9,
			strokeColor: "#FF33FF"
		}
	},
	routeOptions: {},
	reportOptions: {}
});

Route Arrows

You now have ability to either have arrows spaced evenly along your route, or have a single arrow placed at the end of your route. These arrows are customizable in terms of style, spacing, and size. Everything is done through the style parameter inside the functionOptions of the addRoute function call. The settings/options are layed out in the table below.

Property	Type/Values	Description
`arrows`	`"line"\|"end"\|null`	This setting is used to enable the arrow functionality and indicate whether arrows should be placed along the line ("line"), or if a single arrow should be placed at the end of the route ("end"). The default value for this setting is `null`, which indicates that NO arrows should be drawn on the route.
`arrowSize`	`number/string`	The size of the arrow(s) either as a number representing the point radius of the arrow, or a string indicating the size of the arrow as a percentage of the route line's stroke width. Default "100%".
`arrowSpacing`	`number`	For "line" arrows only. The distance in pixels between arrows along the route. Default is 100.
`arrowStrokeColor`	`string`	Hex stroke color. Used as the color for the outline of the arrow(s). Default is "black".
`arrowStrokeWidth`	`number`	Pixel stroke width. Used as the thickness for the outline of the arrow(s). Default is 1.
`arrowStrokeOpacity`	`number`	Stroke opacity (0-1). Used as the opacity for the outline of the arrow(s). Default is 1.
`arrowFillColor`	`string`	Hex fill color. Used as the color for the inside of the arrow(s). Default is "white".
`arrowFillOpacity`	`number`	Fill opacity (0-1). Used as the opacity for the inside of the arrow(s). Default is 1.

Arrows Along Route

The following piece of sample code demonstrates a route with arrows spaced at 50 pixels and sized at "100%".

//ALKMaps.APIKey = "YOUR_KEY_HERE";
		
var map = new ALKMaps.Map("map");
var layer = new ALKMaps.Layer.BaseMap( "ALK Maps", {}, {displayInLayerSwitcher: false});
map.addLayer(layer);
					
map.setCenter();
					
var routingLayer = new ALKMaps.Layer.RailRouting( "Rail Route Layer" );
map.addLayer(routingLayer);
var stops = [
  {
      "format": "StationState",
      "name": "Denver CO",
      "railroad": "UP"
  },
  {
      "format": "StationState",
      "name": "Oakland CA",
      "railroad": "UP"
  }];				
routingLayer.addRoute({
	stops: stops,
	functionOptions:{
		routeId: "DenverToOaklandCA",
		style: {
			arrows: "line",
            arrowSize: "100%",
            arrowSpacing: 50
		}
	},
	routeOptions: {},
	reportOptions: {}
});

Arrow at End of Route

The following piece of sample code demonstrates a route with a single arrow at the end of the route sized at "250%".

//ALKMaps.APIKey = "YOUR_KEY_HERE";
		
var map = new ALKMaps.Map("map");
var layer = new ALKMaps.Layer.BaseMap( "ALK Maps", {}, {displayInLayerSwitcher: false});
map.addLayer(layer);
					
map.setCenter();
					
var routingLayer = new ALKMaps.Layer.RailRouting( "Rail Route Layer" );
map.addLayer(routingLayer);
var stops = [
  {
      "format": "StationState",
      "name": "Denver CO",
      "railroad": "UP"
  },
  {
      "format": "StationState",
      "name": "Oakland CA",
      "railroad": "UP"
  }];			
routingLayer.addRoute({
	stops: stops,
	functionOptions:{
		routeId: "DenverToOaklandCA",
        showHandles: false,
		style: {
			arrows: "end",
            arrowSize: "250%",
            strokeColor: "blue",
            arrowFillColor: "black"
		},
        success: function(){
             map.setCenter(stops[1],10);           
        }
	},
	routeOptions: {},
	reportOptions: {}
});

SPLC Display

The following piece of sample code demonstrates plotting of rail location SPLCs.

//ALKMaps.APIKey = "YOUR_KEY_HERE";
var map = new ALKMaps.Map("map");
var lon = -96, lat = 40, zoom = 4;
var lonLat = new ALKMaps.LonLat(lon, lat).transform(new ALKMaps.Projection("EPSG:4326"), map.getProjectionObject());
var layer = new ALKMaps.Layer.BaseMap("ALK Maps", {}, {
    displayInLayerSwitcher: false
});
var vectorLayer = new ALKMaps.Layer.Vector("Vector Layer");
map.addLayers([layer, vectorLayer]);
map.setCenter(lonLat, zoom);

var splcs = ['860132000', '845200000', '344770000', '854550000']
for (var i = 0; i < splcs.length; i++) {
    var splc = splcs[i];
    ALKMaps.Services.getRailStations({
        splc: splc,
        success: function(resp) {
            var info = resp.GeocodeInfos[0];
            var lon = info.Longitude / 1000000;
            var lat = info.Latitude / 1000000;
            var stationName = info.StationName;
            var pointFeature = new ALKMaps.Feature.Vector(
                new ALKMaps.Geometry.Point(lon, lat).transform(new ALKMaps.Projection("EPSG:4326"),
                    map.getProjectionObject()),
                null, {
                    pointRadius: 8,
                    fillColor: "#4444FF",
                    label: stationName,
                    labelYOffset: 20,
                    fontWeight: "bold",
                    fontColor: "#0000AA"
                }
            );
            vectorLayer.addFeatures([pointFeature]);
        }
    });
}