All Visual API URLs have the following components:
Below we discuss each part in detail.
Here is an example URL and the tile image returned:
http://visual.mapfluence.com/tile/d/from=us_census00.state_geom|mode=simple|colors=ffcccc|border=faa_0.75/ol/4/4/6.png
The base path for a tile URL is:
http://visual.mapfluence.com/tile/
Map globals determine characterstics of the entire tile. Background color may be set here,
or supply d to use default:
d
A layer is a set of key=value clauses, delimited by the pipe "|" character. These include:
- from, required to identify the geometry set to be rendered
- mode, required to describe the style mode
- other parameters which may be required depending on the mode
- other optional parameters, such as border
This layer definition has four keys -- from, mode, colors, and border:
from=us_census00.state_geom|mode=simple|colors=ffcccc|border=faa_0.75
For readability, the examples will show them like this:
from=us_census00.state_geom|
mode=simple|
colors=ffcccc|
border=faa_0.75
A tile can have multiple layers . See Other Topics for more information.
The tile coordinate identifies the spatial location of the tile:
ol/4/4/6
| meaning |
value |
|---|
| map type |
ol |
| zoom |
4 |
| tile x |
4 |
| tile y |
9 |
Mapfluence supports three different tile coordinate systems:
Major map APIs will set coordinates for you -- see map integration for more information.
MapTiler is a useful site for comparing tile coordinates in different systems.
The type of the image to return. At present, only png is supported:
.png
These clauses are required for almost every layer definition.
required
In the from clause, you specify the code name of the geometry set to render.
This one shows US State geometries:
from=us_census00.state_geom
required
mode determines how a layer styles its geometries.
simple shows all geometries the same way -- with a single color:
mode=simple|
colors=fcc|
border=c33_0.25
- simple mode notes:
- polygon layers may use a border in addition to colors (as shown above).
- Layers of point geometries can specify icons instead of colors.
theme styles each geometry by categorizing the numeric value of its select attribute.
breaks mark category boundaries and colors style the categories.
This example shows the unemployment rate from September 2008:
from=us_census00.county_geom|
mode=theme|
select=unemplmnt.data@2008-09.unemprate|
colors=fcc,f00|
breaks=5,10,15
- theme mode notes:
- Geometries with null values will be shaded with the default_color if present, otherwise they will not be shown.
class styles a geometry by its class.
A geometry's select attribute is matched to a value in the values clause.
The layer then styles the geometry with the corresponding color:
select=us_census00.place.place_type|
values='village','municipality','town','CDP','borough','city'|
colors=edbc9a,9cb6a5,7d449e,e41865,b45c21,666666
- class mode notes:
- There must be a corresponding color for every value.
- For point geometries, icons may be given instead of colors.
- If a geometry's select attribute is not in the values list,
it will be shaded with the default_color if present,
otherwise it will not be shown.
Label layers display a text label in the position of the geometry.
The label text is specified by the select attribute.
This example shows Zip Codes in Oakland, CA:
from=us_census00.zcta_geom|
mode=label|
select=us_census00.zcta.id|
size=12|
halo_radius=2|
fill=933
- label mode notes:
- This example shows a label layer composited onto a simple layer with the Zip Code boundaries.
- There are many optional parameters for label layers besides size, halo_radius, and fill, which are used above.
For a complete list, see Mapnik TextSymbolizers.
- The available font faces page lists names suitable for use with the face_name parameter.
heatmap mode is a stylized representation of point density.
This shows the density of EPA Superfund sites in San Jose, CA:
from=epasuperfnd.sf2006_geom|
mode=heatmap|
colors=00c0,8f88,ff8c,ffff
- heatmap mode notes:
- A heatmap layer interprets the colors list as a gradient palette.
- You may specify a select clause.
If present, select will be used to determine each point's intensity,
otherwise each point will be considered to have the same intensity.
- You may specify a density_scale clause.
The intensity of each point will be multiplied by density_scale.
- density_scale is useful for adjusting the appearance of a heat map.
- heatmap mode can't be used with polygon or line geometry types.
usually required
The renderer styles a geometry based on the value of the attribute identified in the select clause.
It takes one of these forms:
dataset.attribute_table.attribute
dataset.attribute_table@period.attribute
Here are examples of select clauses:
select=us_census.zcta.name
select=unemplmnt.data@2008-09.unemprate
select's exact meaning depends on the mode used:
| mode |
meaning of select |
|---|
| simple |
none, ignored |
| theme |
value to determine breaks category |
| class |
value to determine class |
| label |
field containing label text |
| heatmap |
"intensity" of point optional |
This example layer shades US counties by their September 2008 unemployment rate:
from=us_census00.county_geom|
mode=theme|
select=unemplmnt.data@2008-09.unemprate|
colors=fcc,f00|
breaks=5,10,15
usually required
A list of colors to be applied to the geometries of the layer.
Describing Colors explains the syntax in detail.
This example colors three US States by name:
colors=E9967A,crimson,b22
line and point geometry sets will require a size with each color:
ff0000_5
Only label mode layers do not require colors.
These clauses are optional or only relevant for certain modes or geometry types.
optional
where filters the geometries that are shown. The syntax is the same as for Spatial Query where.
This layer shows only ZCTAs (Zip Codes)
whose area is less than 5000000 square meters:
from=us_census00.zcta_geom|
where=area__lt:5000000|
mode=simple|
colors=fcc|
border=cc3333_0.25
And this layer shows a single ZCTA by id:
from=us_census.zcta_geom|
where=id:'359317'|
mode=simple|
colors=fcc|
border=cc3333_0.25
optional
For point geometry sets, a list of icons can be used in place of colors.
The syntax for an icon is one of:
icon_name
icon_name_size
icon_name_widthxheight
iconName is the name of the icon -- choose from Available Icons.
width, height, and size are given in pixels.
size scales the icon proportionally to a maximum of size pixels in either dimension.
If no dimensions are given a (small) default size will be used.
Here are some examples:
| name |
image |
| icon_air_transportation |
 |
| icon_coffee_shop_24 |
 |
| icon_baggage_claim_28x15 |
 |
Icons on a tile:
icons=icon_right_and_down_arrow_inv_20
class mode only
List values of the select attribute which determine classes for this layer.
values notes:
- string values must be enclosed by single quotes "'" (including integers in character type columns)
See Class mode for more information.
optional, only for polygon layers
Draw a border around every polygon. Supply border in "line" format:
border=cc3333_2
theme mode only
A list of breaks describes the numeric ranges by which a theme mode layer will categorize its geometries.
There should be one more color than the number of breaks.
If there is not, the colors will be interpolated along a gradient.
Returning to the September 2008 unemployment example, see that the breaks are 5, 10 and 15 percent:
from=us_census00.county_geom|
mode=theme|
select=unemplmnt.data@2008-09.unemprate|
colors=fcc,f00|
breaks=5,10,15
optional
Supply either or both of min_zoom and max_zoom to display a layer only at certain zoom levels.
This tile definition has multiple layers which show state boundaries at or below zoom level 6,
and county boundaries at zoom level 7 and above:
from=us_census00.state_geom|
colors=ffcccc|
border=black_0.75|
max_zoom=6|
mode=simple
/
from=us_census00.county_geom|
colors=ffffcc|
border=black_0.75|
min_zoom=7|
mode=simple
The Florida Keys at zoom 6:
With the same layer definitions, at zoom 7:
optional, only used by heatmap
The density_scale is a multiplier for the intensity of a point displayed in a heatmap layer.
Compare these images:
density_scale=1
density_scale=3
See Heatmap for more information.
optional, only used by class and theme
When the select attribute for a geometry is null, (or unclassed in a class layer),
the default_color is used.
Modifying a previous example, the default_color is set to a light violet:
default_color=steelblue
If no default_color is given, the renderer will not draw geometries whose attribute is null or unclassed.
See Describing Colors for color syntax.
It is possible to composite multiple layers together into a single tile by
providing two or more layer definitions separated by a forward slash "/":
<layer definition 1>/<layer definition 2>/...
Here is an example of an icon layer composited on top of zip codes:
from=us_census00.zcta_geom|mode=simple|...
/
from=epasuperfnd.sf2006_geom|mode=simple|...
Layers are composited one on top of another, with the first layer supplied (left-most in the URL) at the bottom.
A background color may be supplied in map globals:
bg_color=coral
If no background color is supplied, the background will be transparent.
colors, values, and breaks take a list for a value.
For a list, delimit elements with a comma ",".
The sample layer definition below has values and colors lists:
from=pd_wb.borders|
mode=class|
select=pd_wb.borders.fips_code|
values=US,CA,MX|
colors=00ff99,6633aa,cc9933
