8  REST for Thematic Layers

A thematic layer uses visual differences (color and/or opacity) to distinguish the geometries of features (e.g. counties, states, etc.) with quantitatively different values of a given numeric attribute. These differences relate to variations in the value of the selected property, but instead of classes based on an abstract definition (e.g. "chartered city", "unincorporated," etc.), the property is numeric and the differences are quantitative. For example, if the property you are interested in mapping is median household income, you might use a thematic layer with five colors for five different income ranges (e.g. under $20,000, $20,000 to $50,000, $50,000 to $100,000, $100,000 to $200,000, and over $200,000).

Another application of thematic layers might be to map the relationship between location and voting history. The mapfluence data catalog, for example, includes information on the proportion of votes in various jurisdictions that were cast for the Democratic candidate in the 2008 presidential election. The following steps illustrate how to map election results in a thematic layer with counties divided into six color categories based on their proportion:

1.  Start with the host, version, API key, and endpoint:


2.  Add the layer definition, which means specifying the values of the required layer properties, separating each property value pair with a pipe:
- mode=theme: the layer type, in this case theme.
- select=umi.us_elections.2008_pres.prt_dem_pty: the source of the data by which the geometries will be categorized, in this case an attribute table containing the proportion of the vote that went to the candidate of the Democratic party in the 2008 presidential election.
- from=umi.us_census00.county_geometry: the source of the geometries that will be overlaid, which is the geometry table in the U.S. Census dataset covering U.S. counties.
- breaks=0.33,0.45,0.5,0.55,0.67: a list of break points within the valid range of numeric values for the attribute, in this case the proportion of voters who voted for the Democratic candidate. These five breaks create six categories of geometries (counties) based on the percent of voters voting Democratic: less than 33%, 33-45%, 45-50, 50-55%, 55-67%, and over 67%.
- border=808080_1: the color and line weight of the border, which shows the boundaries between geometries.
- styles=ff0000,ff8000,ffff00,00ff00,008080,0000ff: a list of colors (red, orange, yellow, green, teal, blue) that will be used to render the categories of geometries defined by breaks.
- opacity=0.5: the overall opacity of the layer. This is an alternative to adding an alpha channel specification to the end of each color in the styles property.
In a thematic layer, styles is plural.


3.  Add the base map code (in this case for Google Maps) after the layer definition:


4.  Add a query string after the base map code to specify the map's centerpoint, size, and zoom:


5.  Put it all together and you have the complete REST path for the map:


Here's an excerpt of the map, showing the proportion of voters in each county that voted Democratic in the 2008 presidential election, that is returned from the above URL (to see the full map in a new window, click here):

Note: For complete details on the purpose and valid values of thematic layer properties, both required and optional, refer to the Thematic Layer page of the Mapfluence REST API Reference at http://developer.urbanmapping.com/docs/mapfluence/rest/2.0/reference/tile/layer/Thematic.