de/numerics have released a web service for creating heatmap translucent color overlays of geographic-based data on Google maps. No programming is required, but this service can be accessed using a PHP API. This article shows you how to use this service using the PHP programming interface.

Accessing the service

You can just cut and paste your data into the heatmap demo page to get one-off maps with no programming required, or, if you know how to program, you can drive the service from your own web site in order to automatically make color overlaid maps to display-- all with the full Google Dynamic Maps flexibility of pan/zoom/road map/satellite images/terrain images, etc.

Data format

The service takes data in the form of numeric triples (latitude, longitude, DATA), where DATA is any numeric value.  The service will compute a blended color contour based upon the data and display it on top of a Google map which is automatically centered at the centroid of the set of your (latitude,longitudes).   The centroid is at the statistical “mean” or average latitude and longitude of your data set.  At least two data points must be provided, but results may not make sense unless you have at least three or four data points.

Programming the service in PHP

This article describes how to integrate the service into your web pages using the PHP web development language, with the PHP running on a web server.  A full manual with graphical examples is provided, that describes the options available for modifying the graphical overlay display.  The heatmap demo page is written in JavaScript. By using your browser’s View Source window, this provides a JavaScript example of driving the service from a web client.

While reading this article, you may want to open the full Google heatmap example code in a separate window for reference.  This is PHP code surrounded by HTML syntax and can function as a web page if you want to use it as-is or modify it for your purposes.  If you do this, be sure to name the file with a .php suffix and not  a .txt suffix to insure that it runs as a PHP script. This discussion will cover the PHP code between the brackets.

Full reference code can be found at  http://diffent.com/map/phpdriver.txt

The first thing we do is to set the URL of the service, and the data points we want to display, in string variables:

$url ='http://diffent.com/map/mapit9.php';

// In the $points string variable, the format requirement is
// to separate successive numbers by at least one blank space.
// No need to put the successive points on successive lines.
// This $points can be of course filled programmatically rather than
// hard coded as in this example.

//               lat      long    data
$points =     '34.0   -118.4    3.0
               34.1    -118.5     2.2
               34.2    -118.4     2.9
               34.15   -118.3     4.4
               34.2    -118.6     1.5';

As you can see here, the points can be free-formatted in the string.  The only requirement is that each number is separated by a blank space or other “white space” character such as tab or carriage return.  The points need not be on separate lines.  For your use, you will likely be extracting the points from a database or some other source and then assembling them into the $points string variable, by concatenation, using the “dot” operator:

$points =           $lat1 . " " . $long1  . " " . $data1 . " " ; // 1^st point w/ blank at end
$points = $points . $lat2 . " " . $long2  . " " . $data2 . " ";   // tack on the 2^nd point

// etc

You could of course do the concatenation in a loop if you have a lot of points. There are many string operators in PHP, and you just need to use them to manipulate your data into a string of the above form.

Next, we set up an array that has all the point data that we want to send to the service, along with the graphic settings that we want.

Full descriptions of these settings are on the heatmap demo page user interface and in the user manual, but a brief description is as follows:

xresInput                  horizontal resolution in number of color-squares of the overlay

yresInput                  vertical resolution in number of color-squares of the overlay

lowercutoffInput     cutoff value (in percent, 0.0 to 1.0 form)...overlay color squares that

                                    have a color value lower than this, will not be shown.

                                    This is in the units of a zero-to-one normalized version of your data range.

                                    Eg. set this to 0.3 if you want to not show the lower 30% of the range of

your data.

blendInput                This is a blend exponent value.  Set this lower to get a smoother blend

                                    or more filtering, set this higher to do less filtering and less smoothing

                                    (showing more local behavior of your data).  Typically, numbers

                                    of 5 to 30 give reasonably blended color displays of your data.

xsizeInput                These two values are the size in pixels of the generated map.

ysizeInput

$fields = array('thedata'=>urlencode($points),
                'xresInput'=>urlencode('20'),
                'yresInput'=>urlencode('20'),
                'lowercutoffInput'=>urlencode('0.0'),
                'blendInput'=>urlencode('7'),
                'xsizeInput'=>urlencode('800'),
                'ysizeInput'=>urlencode('600')                 );

Note that all numeric values in the above should be set as strings.

Next, we combine all of the data fields together into one string separated by ampersands, because we will be using the standard HTTP POST method of sending data or “arguments” to a PHP page.  Note that each value we send gets put into name=value form, e.g. ysizeInput=600, and each of these name=value pairs is separated by an ampersand.

foreach($fields as $key=>$value) {$fields_string .= $key.'='.$value.'&';}

Next, we remove the final ampersand...we don't want one at the end. There may be an easier way to do the above loop and following rtrim() using the PHP string “implode()” function (for you professional PHP programmers), but we want to be explicit in this example.

rtrim($fields_string,'&');

Now we have all the data we need to launch the service. 

To invoke the map overlay service with these arguments and your data, we will use the CURL module of PHP (often written as cURL or libcurl).  CURL stands for “Command line URL” which seems to indicates its origin...on command line systems (like Linux), you could send HTTP or other web-related requests easily, without a browser being open, e.g. to retrieve data from a web site without displaying the site — say, for automation purposes in a script.

You must be sure that your internet service provider supports the CURL module for PHP.  This sample was written with a bare-bones web hosting service and this provided CURL, so it is probably not an exotic feature of PHP.  You will probably have it available.

First, we initialize the CURL service and store a handle to it in the $ch variable:

$ch = curl_init();

Next, we set the various CURL options we need, using the curl_setopt function.  Note that this sets the options (in upper case below) for the $ch CURL handle we just made.

We set the URL, how many variables we are going to send it (via the count() function) and the variables encoded into the $fields_string which we made above:

curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_POST, count($fields));
curl_setopt($ch, CURLOPT_POSTFIELDS, $fields_string);

We then send all this information to the CURL subsystem. The CURL subsystem goes out to the web, sends the data and display arguments to our map overlay URL using the HTTP POST mechanism, and displays the resulting overlaid Google heatmap in the current browser window  :

$result = curl_exec($ch);

Finally, we close the CURL subsystem:

curl_close($ch);

So that's it for basic programming of the service.  Displaying the map in a separate window or a separate frame of the current browser requires some additional PHP and/or HTML coding beyond the scope of this document.  However, those are the basics, and should get you started programming to the de/numerics Google heatmap overlay service.

If this coding is too complicated for your expertise, remember that you can always just paste your data into the heatmap demo page itself and use the service as a cut & paste manual service.

About

de/numerics is a subsidiary of Differential Enterprises LLC, a digital technology consulting and development company specializing in numeric forecasting and high speed computing using NVIDIA desktop supercomputers.