Mago HeatMap API 2.0

What is it and what is it good for?

Mago HeatMap map layers generator is designed to display large amounts of data on maps. Use of offers, for example, a better view of the real estate prices, election results and generally to display values ​​in relation to any location.

Calculation of map plates in real time, and can therefore display both static and dynamic data, for example, to create a map of the current temperature, air quality and traffic congestion.

History, restrictions and price

The first version of Mago HeatMap was established in July 2011, the second (current - mainly differ in the client part) in November 2011. Both are currently running on a single virtual machine, which can affect overall service performance and availability - estimated limit the number of requests is estimated between 500-700 thousand per 24 hours. For these reasons, imposed certain restrictions, you may be in agreement in a particular case, modify, or remove it entirely.

• Processed only the first 10000 coordinates in the data source and the first 16 color custom color scale.
• Data from the data source will be loaded only once per hour and subsequently placed in a cache server. In the absence of memory can be a source of data queried frequently.
• Availability is not guaranteed and the operation may be terminated at any time.

The service is provided free with the above limits.

In case of requirement of processing large volumes of data, or better response time and availability please write to kontakt@mago.cz.

The input data format

Mago HeatMap retrieves data from an external XML file, which must include latitude, longitude, and height / point value. Can i transfer are transferred to the Mercator projection.

Example of a data source:

<data>
	<colors> 
		<!-- AARRGGBB -->
		<color value="FFFF0088" />
		 <color value="60FF0000" />
		...
	</colors>
	<points> 
		<!-- WGS84 -->
		<point lat="50.1355" lng="15.29" z="123"/>
		<point lat="50.334" lng="14.543" z="15.56"/>
		<point lat="50.334" lng="14.543" z="15.56"/>
		<!-- Mercator -->
		<point x="140.85473116" y="87.23271434" z="120.75"/>
		<point x="138.25496811" y="86.72380396" z="3.7"/>
		...
	</points>
</data>

Reference and Examples

The server part API

1. At http://api.mago.cz/heatmap.v2/reg.ashx must apply to register the data source. They are expected parameters u (address data source) and e (e-mail address of the contact). Send request as HTTP POST.
2. A successful registration returns a JSON response (application/json), where the parameter StatusMessage contains a unique key needed further.
3. Map tiles generators http://api.mago.cz/heatmap.v2/map.ashx and http://api.mago.cz/heatmap.v2/hexa.ashx receives GET parameters:
   • id - the key is returned upon successful registration (mandatory).
   • x, y, z - coordinates of the plate and the selected map scale (mandatory). For more information use Custom Map Types as help for Google Maps API.
   • r - radius of the averaging (mandatory in the range 16 to 255).
   • c - the color table number (mandatory in the range 0 - 4).
   • s - rendering style (mandatory in the range 0 - 2; = 0 map, 1 = only points, 2 = map with points).
   • a - alpha [0..255] - transparency (default 128).
   • d - diameter [16..96] - influences and hexa-point tile generation.
4. Legend for the map data can be obtained http://api.mago.cz/heatmap.v2/legend.ashx and accepts these parameters:
   • id - the key is returned upon successful registration (mandatory).
   • c - the color table number (mandatory in the range 0 - 4).

The client part API - jQuery plugin

It is expected to run over the Google Maps API v3 or Leaflet 0.7 supplemented with the use of jQuery least version 1.5.1.

Current version of the library is located at http://api.mago.cz/heatmap.v2/heatmap.2.js.

Example of using the Google Maps API v3:

...
<script type="text/javascript">
	$().ready(function () {
		var map = new google.maps.Map(document.getElementById("map"), {
			zoom: 8,
			center: new google.maps.LatLng(49.83608, 15.51494),
			streetViewControl: false,
			mapTypeId: google.maps.MapTypeId.ROADMAP,
			maxZoom: 20,
			minZoom: 7
		});
		$(map).HeatMap({
			dataUrl: "http://api.mago.cz/heatmap.v2/examples/data-2.xml",
			email: "kontakt@mago.cz"
		});
	});
</script>
...
<div id="map"></div>
...

Example of use with Leaflet 0.7 and tiles from OpenStreetMap:

...
<script type="text/javascript">
	$().ready(function () {
		var map = L.map("map").setView([49.83608, 15.51494], 8);
		L.tileLayer("http://{s}.tile.osm.org/{z}/{x}/{y}.png", {
			attribution: "© <a href=\"http://osm.org/copyright\">OpenStreetMap</a> contributors"
		}).addTo(mapOSM);
		$(map).HeatMap({
			dataUrl: "http://api.mago.cz/heatmap.v2/examples/data-2.xml",
			email: "kontakt@mago.cz"
		});
	});
</script>
...
<div id="map"></div>
...

Default settings of the plugin is:

var defaults = { 
	root: "http://api.mago.cz/heatmap.v2/",
	alpha: 128,
	radius: 64,
	style: 0,
	colorSchema: 0,
	tileType: "map",
	diameter: 16,
	onError: function (data) { 
		if (window.console && window.console.error) 
			window.console.error("err: " + data.statusMessage);
		else 
			if (window.alert) 
				window.alert("err: " + data.statusMessage);
	}, 
	onRegistered: function (data, mapType) { 
		if (data.mapObject.overlayMapTypes) 
			data.mapObject.overlayMapTypes.push(new google.maps.ImageMapType(mapType));
		if (data.mapObject._leaflet_id) 
			mapType.addTo(data.mapObject);
	}
} 

When an error in the registration of resources will call onError event (data) and data variables will return one of the following conditions:

var data = { 
	statusMessage: "Missing or incorrect URI.",
	statusCode: -3
} 

var data = { 
	statusMessage: "Missing or incorrect Email.",
	statusCode: -4
} 

var data = { 
	statusMessage: "Incorrect URI, missing Email or limit per URI authority exceeded.",
	statusCode: -1
} 

var data = { 
	statusMessage: "Data loading or data parsing error.",
	statusCode: -2
}

After successful registration are onRegistered (data, mapType) provide the following variables:

var data = {
	statusMessage: "", // vygenerované id datové sady
	statusCode: 1,
	pointsTotal: 0, // počet zpracovaných bodů
	colorsTotal: 0, // počet zpracovaných barev
	legendUrl: "",  // odkaz na generátor dat pro stavbu legendy
	mapObject: null // object Google Maps or Leaflet
}

// when using Google Maps
var mapType = { 
	getTileUrl = function(coord, zoom) { ... },
	tileSize: new google.maps.Size(256, 256),
	isPng: true
}

// when using Leaflet
var mapType = L.tileLayer("...", {})

What is going on?

• Security of data files and emails.
• Handler for an accurate reading values.
• Generator text list of points values ​​and descriptions (JSON) to pictorial boards. It will thus create maps with the ability to inform on each item and the board.
• New styles view point of a group of points (circle, square, triangle, etc.).

Questions and suggestions sent to kontakt@mago.cz.