The Task

You're going to build a house hunting research application. People don't know exactly where they want to live, but they know they care about schools, economics, transit, and environmental hazards of a place. We will build a map, step-by-step, that will help them find areas that meet their criteria.

EasyMap

To start, we take a shortcut: the EasyMap web service. With it, you avoid having to craft HTML or Javascript. That comes later. The examples will be overlain on a Bing Map, but they could easily overlay a number of others.

Layer Style Specifications

A layer is one set of geometries drawn in a particular way. Points can be drawn as points, icons, or heatmaps. Lines may be drawn with color and widths, and polygons with color, borders, and labels. A layer specification is made up of a number of parameters that instruct the Visual API how to draw the information. An example is thus:

from=us_census00.zcta_geom|mode=simple|border=black_1|colors=clear

By the end of this tutorial, we promise you'll understand what it means.

Mapping Point Locations

SELECT geometry
FROM epabrnfld.bf2009_geom
WHERE epabrnfld.bf2009.air_f = 't'

http://lab.mapfluence.com/map/d/from=epabrnfld.bf2009_geom|where=epabrnfld.bf2009.air_f:t|mode=simple|colors=black_7/ve/?lng=-97.337545&lat=37.692236&zoom=3

http://visual.mapfluence.com/map/d/
from=ntad_airports.arpt_loc_geom|mode=simple|
icons=icon_air_transportation_24x20/ve/?zoom=8

Mapping Polygons

http://visual.mapfluence.com/map/d/select=us_census00.stats.med_hv|from=us_census00.tract_geom|where=us_census00.stats.med_hv__lt:400000|mode=simple|colors=yellow/ve/

http://visual.mapfluence.com/map/d/select=us_census00.stats.med_hv|from=us_census00.tract_geom|breaks=200000,400000,600000,800000,1000000|mode=theme|colors= white,blue,green,yellow,orange,red/ve/

http://visual.mapfluence.com/map/d/
from=us_schl_dists.uni2008_geom|
mode=simple|border=black_1|colors=clear/ve/

Multiple Layers

You have all these individual maps, but you want to put them all together. The full URL syntax looks like:

http://visual.mapfluence.com/map/d/<layerspecs>/<maptype>/

and end with the same thing -- /g/, /ve/, or /tms/.

For the layerspecs, join order them together with a slash (/) ordered from bottom to top:

• select=us_census00.stats.med_hv|from=us_census00.tract_geom|mode=theme|breaks=200000,400000,600000,800000,1000000|colors=FFFFFF80,0000FF80,00FF0080,FFA50080,FF000080
• from=us_schl_dists.uni2008_geom|mode=simple|border=black_1|colors=clear
• from=schoolperfed_com.sch_info_geom|mode=simple|colors=black_7
• from=ntad_airports.arpt_loc_geom|mode=simple|icons=icon_air_transportation_24x20

The result looks like this:

http://visual.mapfluence.com/map/d/select=us_census00.stats.med_hv|from=us_census00.tract_geom|mode=theme|breaks=200000,400000,600000,800000,1000000|colors=FFFFFF80,0000FF80,00FF0080,FFA50080,FF000080/from=us_schl_dists.uni2008_geom|mode=simple|border=black_1|colors=clear/from=schoolperfed_com.sch_info_geom|mode=simple|colors=black_7/from=ntad_airports.arpt_loc_geom|mode=simple|icons=icon_air_transportation_24x20/ve/

Moving to Javascript

EasyMap is a shortcut.

To embed maps in a Javascript/HTML page, you need a little bit of scaffolding. You need to include some scripts, set up your HTML, include an UMI API key, and so on.

The best way to get started with Javascript is to just pick one of the map URLs above that looks similar to what you are interested in, and copy and modify it.

Take a look at the code. Regardless of which mapping framework you are using, their mapping API allows you to specify a tile template: a URL pattern with slots held open for the mapping framework to put specific tile coordinates into. For Bing Maps, the template for the housing price map is created with the following code:

function tilePath(tileContext)
{
    return "/tile/1.0.0/d/select%3Dus_census00.stats.med_hv%7Cfrom%3Dus_census00.tract_geom%7Cmode%3Dtheme%7Cbreaks%3D200000%2C400000%2C600000%2C800000%2C1000000%7Ccolors%3DFFFFFF80%2C0000FF80%2C00FF0080%2CFFA50080%2CFF000080/g/" + tileContext.ZoomLevel + '/' + tileContext.XPos + '/' + tileContext.YPos + '.png?apikey=YOUR_API_KEY';
}

function GetTiles()
{
    var bounds = [new VELatLongRectangle(new VELatLong(90,-180),new VELatLong(-90,180))];

    var tileSourceSpec = new VETileSourceSpecification("overlay", "");
    tileSourceSpec.NumServers = 1;
    tileSourceSpec.Bounds = bounds;
    tileSourceSpec.MinZoomLevel = 0;
    tileSourceSpec.MaxZoomLevel = 16;
    tileSourceSpec.Opacity = 1;
    tileSourceSpec.ZIndex = 100;
    tileSourceSpec.GetTilePath = tilePath;

    map.AddTileLayer(tileSourceSpec, true);
}

You should recognize the stuff in the middle of tilePath as the url-encoded layer specification. The tileContext.ZoomLevel, .XPos, and .YPos are all instructions for which tile to fetch, which the Bing Maps API framework passes in (indirectly). Google Maps and TMS do much the same thing.

While you can now skin this page to your heart's content, it's still a little bit difficult to change things programmatically, like if you want to add checkboxes to show/hide the different layers. It is possible with this style of map, but your life will be better if you read on to the next section.

Advanced Javascript

Mapfluence offers a Javascript API for creating layer (tile) specifications, that will work will in a dynamic user interface: turn layers on and off, change breaks, etc. You can also make maps with Javascript objects.

Bing (VE), Google, Cloudmade, and TMS (OpenLayers), each have convenience classes - TileManagers - to make life a little easier:

function GetMap()
{
   map = new VEMap('myMap');  // connects the map div to the API
   map.SetDashboardSize(VEDashboardSize.Small);
   map.LoadMap(new VELatLong(37.76,-122.4),11,'r' ,false);

   mgr = new MF.VE.TileManager({
       opacity: 0.5,
       tileSpec: new MF.Render.TileSpec({
           layers: [
                   new MF.Render.SimpleLayer({
                           from: 'ntad_airports.arpt_loc_geom',
                           icons: 'icon_air_transportation_24x20'})
                   ] // use the same parameter names and values
        })
   });

   mgr.overlay(map);  // This is it!
}

You will probably recognize some of the airport map's parameters in the layers field of the tileSpec:

new MF.Render.SimpleLayer({
        from: 'ntad_airports.arpt_loc_geom',
        icons: 'icon_air_transportation_24x20'})

Here is the layer for the schools:

new MF.Render.SimpleLayer({
        from: 'schoolperfed_com.sch_info_geom',
        colors: 'black_7'})

Here is the layer for the median housing price:

new MF.Render.ThemeLayer({
        select: 'us_census00.stats.med_hv',
        from: 'us_census00.tract_geom',
        breaks: [200000,400000,600000,800000,1000000],
        colors: ['FFFFFF80','0000FF80','00FF0080','FFA50080','FF000080']})

Notice that the mode clause shows up in the type of the layer: MF.Render.SimpleLayer for the airports and schools; MF.Render.ThemeLayer for the median housing value layer.

Finally, here is the layer for the school districts:

new MF.Render.SimpleLayer({
        from: 'us_schl_dists.uni2008_geom',
        border: new MF.Render.Border('black','1.0'),
        colors: 'clear'})

To put them all together, just put them all in the layers array. The first layer in the layers array gets drawn first, so we need to order our layers so that the median home value doesn't obscure the other layers:

tileSpec: new MF.Render.TileSpec({
    layers: [
            new MF.Render.ThemeLayer({
                    select: 'us_census00.stats.med_hv',
                    from: 'us_census00.tract_geom',
                    breaks: [200000,400000,600000,800000,1000000],
                    colors: ['FFFFFF80','0000FF80','00FF0080','FFA50080','FF000080']}),
            new MF.Render.SimpleLayer({
                    from: 'us_schl_dists.uni2008_geom',
                    border: new MF.Render.Border('black','1.0'),
                    colors: 'clear'}),
            new MF.Render.SimpleLayer({
                    from: 'ntad_airports.arpt_loc_geom',
                    icons: 'icon_air_transportation_24x20'}),
            new MF.Render.SimpleLayer({
                    from: 'schoolperfed_com.sch_info_geom',
                    colors: 'black_7'})
            ]

To run this, you can go to the Mapfluence API Developer Lab and enter the following full Easy Map example:

// apilab-template: code-evaluates-to-url

var easy_map = new MF.EasyMap({
        tileSpec: new MF.Render.TileSpec({
           layers: [
                   new MF.Render.ThemeLayer({
                           select: 'us_census00.stats.med_hv',
                           from: 'us_census00.tract_geom',
                           breaks: [200000,400000,600000,800000,1000000],
                           colors: ['FFFFFF80','0000FF80','00FF0080','FFA50080','FF000080']}),
                   new MF.Render.SimpleLayer({
                           from: 'us_schl_dists.uni2008_geom',
                           border: new MF.Render.Border('black','1.0'),
                           colors: 'clear'}),
                   new MF.Render.SimpleLayer({
                           from: 'ntad_airports.arpt_loc_geom',
                           icons: 'icon_air_transportation_24x20'}),
                   new MF.Render.SimpleLayer({
                           from: 'schoolperfed_com.sch_info_geom',
                           colors: 'black_7'})
                   ]

           }),
           // map type can be one of 'bing','google','openlayers','cloudmade'
           maptype: 'bing'
})
easy_map.getMapUrl();

Next... The Query API

You've provided the map. But now users have specific questions, "That looks interesting! Tell me more!" That brings us to the Query API: the suite of tools that allow you to answer precise questions about place, and leverage the enormous corpus of data in Mapfluence...

So on to the Query API!