Mago HeatMap API 2.0

Co to je a k čemu je to dobré?

Mago HeatMap je generátor mapových vrstev určený pro zobrazení velkého množství dat na mapách. Využití se nabízí například pro lepší náhled na ceny nemovitostí, volební výsledky nebo obecně pro zobrazení hodnot vázaných k nějaké lokalitě.

Výpočet mapových desek probíhá v reálném čas a lze tedy zobrazovat statická i dynamická data, např. pro vytvoření mapy aktuální teploty, kvality ovzduší nebo hustoty provozu.

Historie, omezení a ceny

První verze Mago HeatMap vznikla v červenci 2011, druhá (aktuální - odlišná hlavně v klientské části) až v listopadu 2011. Obě běží zatím na jediném virtuálním stroji, což může mít vliv na celkový výkon služby a její dostupnost - předpokládaný limit počtu požadavků je odhadován mezi 500 až 700 tisíci za 24 hodin. Z těchto důvodů byla zavedena některá omezení, ty lze po dohodě v konkrétním případě upravit, nebo zcela odstranit.

• Zpracováno bude pouze prvních 10000 souřadnic v datovém zdroji a prvních 16 barev vlastní barevné stupnice.
• Data z datového zdroje budou načítána pouze jednou za hodinu a následně umístěna do cache serveru. Při nedostatku paměti může být zdroj dat dotazován častěji.
• Dostupnost není nijak garantována a provoz může být kdykoliv ukončen.

Služba je provozovaná zdarma s výše uvedenými limity.

V případě požadavku na zpracování většího objemu dat, nebo lepší odezvy a dostupnost pište na kontakt@mago.cz.

Vstupní formát dat

Mago HeatMap načítá data z externího XML souboru, který musí obsahovat zeměpisnou šířku, délku a výšku/hodnotu bodu. Lze předávat i souřadnice převedené do Mercatorova zobrazení.

Příklad datového zdroje:

<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 a příklady

Serverová část API

1. Na adrese http://api.mago.cz/heatmap.v2/reg.ashx třeba požádat o registraci datového zdroje. Jsou očekávány parametry u (adresa datového zdroje) a e (emailová adresa kontaktu). Dotaz posílejte jako HTTP POST.
2. Úspěšná registrace vrací JSON odpověď (application/json), kde parametr statusMessage obsahuje unikátní klíč potřebný dále.
3. O generování desek mapových podkladů se stará http://api.mago.cz/heatmap.v2/map.ashx a http://api.mago.cz/heatmap.v2/hexa.ashx a přijímá tyto GET parametry:
   • id - klíč vrácený po úspěšné registraci (povinné).
   • x, y, z - souřadnice desky a zvolené měřítko mapy (povinné). Bližší informace Custom Map Types v nápovědě ke Google Maps API.
   • r - poloměr oblasti pro průměrování hodnot (povinné v rozsahu 16 - 255).
   • c - číslo tabulky barev (povinné v rozsahu 0 - 4).
   • s - styl vykreslení (povinné v rozsahu 0 - 2; 0 = mapa, 1 = jen body, 2 = mapa i body).
   • a - alpha [0..255] - průhlednost desky (default 128).
   • d - průměr [16..96] - ovlivňuje bodové a hexa zobrazení.
4. Legendu k mapovým podkladů lze získat na http://api.mago.cz/heatmap.v2/legend.ashx a přijímá tyto parametry:
   • id - klíč vrácený po úspěšné registraci (povinné).
   • c - číslo tabulky barev (povinné v rozsahu 0 - 4).

Klientská část API - jQuery plugin

Předpokládá se běh nad Google Maps API v3 nebo Leaflet 0.7 doplněný o použití jQuery alespoň verze 1.5.1.

Aktuální verze knihovny je umístěna na http://api.mago.cz/heatmap.v2/heatmap.2.js.

Příklad použití s 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>
...
	

Příklad použití s Leaflet 0.7 a podklady z 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 nastavení pluginu je:

var defaults = {
	encrypted: "",
	dsid: "",
	root: "http://api.mago.cz/heatmap.v2/",
	dataUrl: "",
	email: "",
	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) {
		switch (data.client) {
			case "apiG":
				data.mapObject.overlayMapTypes.push(new google.maps.ImageMapType(mapType));
				return;
			case "apiL":
				mapType.addTo(data.mapObject);
				return;
		}
	}
};
	

Při chybě v registraci zdroje dojde k vyvolání události onError(data) a v proměnné data bude vracet jeden z těchto stavů:

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
}
	

Po úspěšné registraci jsou v onRegistered(data, mapType) dostupné tyto proměnné:

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 nebo Leaflet
}

// v případě použití Google Maps
var mapType = {
	getTileUrl = function(coord, zoom) { ... },
	tileSize: new google.maps.Size(256, 256),
	isPng: true
}

// v případě použití Leaflet
var mapType = L.tileLayer("...", {})
	

Bezpečnost a soukromí

V případě, že nechcete zveřejňovat email nebo adresu datového zdroje, máte dvě možnosti jak je skrýt před návštěvníky vašich map.

1. Způsob (DOPORUČENO) je použití zašifrovaného emailu a url datového zdoje. Použijte tento folmulář:
   Zadejte url datového zdroje a emailovou adresu

   ...
   $(map).heatMap({
   	encrypted: "QPLWZS1XhWrt/MWVjEAwzhQqEjNTbsG/po3FYEnQYcZGA1+hybfiWku1m7YhVwzYD7KQw7olmMa6dxZYBojLKUrDGcRkI28P7CGjYLbzuA8ibKliakJae8NDlJjRW1t/w3MhaeXs1AaeqLj2q9XEDA=="
   });
   ...
   			

2. Možnost je provést registraci datové sady pouze jednou a následně upravit kód pro použití pluginu HeatMap a nahradit vlastnosti dataUrl a email jedinou vlastností dsid takto:

   ...
   $(map).heatMap({
   	dsid: "6ec6eadb233842beb2db6326f1e2ded6"
   });
   ...
   			

   Tím je sice před návštěvníky skryt email i adresa datového zdroje (a server je nebude vracet v odpovědích), ale vystavujete se nebezpečí, že vaše mapy přestanou zobrazovat heatmap vrstvu. K tomu může dojít v případě, že na straně serveru bude ztracena vazba dsid a dataUrl/email.

Co se chystá dál?

• Handler pro přesný odečet hodnoty.
• Nové styly zobrazení bodu a skupiny bodů (kruh, čtverec, trojúhelník a další).
• Generátor textového seznamu bodů, hodnot a popisů (JSON) k obrázkovým deskám. Půjde tak vytvořit mapy se schopností informovat o každém bodu a desce.

Galerie desek

V levém sloupci vyberte jeden z přednastavených stylů, změna se promítne na mapu vpravo.
Vlastní styl si můžete vytvořit upravením parametrů a barev, jak je uvedeno v přecházejících kapitolách.

Kontakt

Dotazy a návrhy prosím směřujte na kontakt@mago.cz.

Machine-translated: English