Map customization

Map customization allows you to change the appearance of most geo-objects on it. For example, repaint roads or houses in a different color.

Map customization is set using parameter style as a string containing one or more objects, separated by symbol ~:

style=Block1~Block2~...~BlockN

Each block consists of a list of filters and redefined properties, separated by symbol |:

Filter1|Filter2|...|FilterN|Property1|Property2|...|PropertyN

A filter consists of a name, semicolon : and a list of values, separated by symbol ;:

{filter name}:{value1};{value2};...;{valueN}

The following filters are supported:

  • tags.all, tags.any, tags.none — describes to which objects the styling should be applied. For more information, see Tags.
  • types — limits object types, to which the styling will be applied. For more information, see Types.
  • elements — specifies the object elements, the display properties of which are changed. Possible values are described in section Elements.

A redefined property has the following format:

stylers.{property name}:{value}

stylers{zoom range}.{property name}:{value}

The zoom range can be set as [zoom] or [zmin-zmax].

The supported properties are described in section Properties.

Tags

The filters specify a subset of map objects, to which the customization block will be applied.

Most of the objects on the map have one or more tags that help to classify them.

The following filters are supported:

  • tags.all - The object must have all the specified tags;
  • tags.any - The object must have at least one of the specified tags;
  • tags.none - The object must not have the specified tags.

If no filter is present, then the customization block is applied to all map objects.

Alert

If one of the fields contains an unknown tag, the customization block is not applied.

Tags list

The tags of objects depend on the map layer styled. Below are the tags that can be used to change the map substrate.

  • road: Highways:
    • road_N: Highways with category of importance N ranging from 1 (most important) to 7 (least important).
    • road_limited: Roads with restricted motor traffic, pedestrian areas.
    • road_unclassified: Unclassified roads (usually in forests and fields).
    • road_minor: Intra-block passages.
    • road_construction: Roads under construction.
    • ferry: Ferry crossings.
    • path: Roads that are not suitable for motor traffic (sidewalks, park paths, and bicycle paths).
    • crosswalk: Pedestrian and bicycle crossings.
    • traffic_light: Traffic lights.
  • water: Bodies of water:
    • bathymetry: Map of the depth of reservoirs.
  • landscape: Landscape objects:
    • land: Land surface.
    • landcover: Vegetation, swamps, and glaciers:
      • vegetation: Vegetation (including lawns, urban vegetation and point plants).
    • urban_area: Urban blocks:
      • residential: Residential blocks.
      • industrial: Industrial blocks.
      • cemetery: Cemeteries.
      • park: Gardens and parks.
      • medical: Healthcare facilities.
      • sports_ground: Sports grounds and playing fields.
      • beach: Beaches.
      • construction_site: Construction sites.
      • parking: Parkings.
    • national_park: National parks and nature preserves.
    • terrain: Terrain.
  • poi: Points of interest:
    • major_landmark: Prominent objects marked with a separate icon.
    • outdoor: Outdoor playgrounds:
      • park: Gardens and parks.
      • national_park: National parks and nature preserves.
      • beach: Beaches.
    • parking: Parkings.
    • shopping: Stores and shopping malls.
    • commercial_services: Organizations providing commercial services:
      • fuel_station: Gas stations.
      • hotel: Hotels and housing.
    • food_and_drink: Restaurants and bars.
    • cemetery: Cemeteries.
    • medical: Healthcare facilities.
  • admin: Labels and borders of districts, and public spaces in localities:
    • country: Countries.
    • region: Regions or states.
    • locality: Localities.
    • district: Urban districts.
    • address: Addresses.
  • transit: Any map objects related to public transport:
    • transit_location: Any point on the map related to public transport, such as metro stations, bus stops, or entrances.
      • transit_stop: Public transport stops with passenger drop-off and pick-up.
      • transit_entrance: Entrances or exits of a metro station.
    • transit_line: Transit lines as a physical object, such as railway and tram tracks or cable lines above ground.
    • transit_schema: Schematic representation of public transit lines.
    • is_unclassified_transit: Public transport objects of unknown importance.
  • structure: Structures:
    • building: Buildings:
      • entrance: Building entrances.
    • fence: Fences.
  • is_tunnel: A section of road or track passing through a tunnel.
  • geographic_line: Equator line and polar circles.

Types

The filter types specifies map objects' types, to which the customization block is applied. You can set one or more types. Possible values:

  • point — Points. For example, bus stops, POI.
  • polyline — Polylines. For example, roads, borders, riverbeds.
  • polygon — Polygons. For example, parks, lakes.

If no types filter is present, then the customization block is applied to all object types.

Elements

The filter elements specifies map object elements, the display properties of which are changed. Possible values:

  • geometry — Geometric elements of the object (a combination of geometry.fill and geometry.outline).
  • geometry.fill — Inner area (fill) of the object's geometric elements.
  • geometry.fill.pattern — Image that fills the inner area of the polygon or polyline.
  • geometry.outline — Outline of the object's geometric elements.
  • label — All elements of the object label.
  • label.icon — Object icon.
  • label.text — Text of the object label (a combination of label.text.fill and label.text.outline).
  • label.text.fill — Fill of the object label text.
  • label.text.outline — Outline of the object label text.

If no elements filter is present, then the properties in the customization block will be changed for all elemnts of the map objects.

Properties

The supported redefined properties are (applied in this order):

  • visibility: Sets the visibility of the object. Possible value: off.
  • hue: Changes the hue of the object on the map without changing its saturation and brightness. Set as a base color in RRGGBB format (see the description of the color property). For a base color with an undefined hue (white, gray, or black), the color of the object doesn't change.
  • saturation: Changes the color saturation on the map. Set as a real number from the range [-1, 1]. At -1, all colors become shades of gray. At 1, the image colors become highly saturated. At 0, the colors don't change. Shades of gray don't change.
  • lightness: Changes the brightness of colors on the map. Set as a real number from the range [-1, 1]. At -1, all colors become black. At 1, all colors become white. At 0, the colors don't change.
  • color — Changes the object color (if applied to an icon, its primary color). The following formats are supported:
    • RGB, RRGGBB, 0xRGB, 0xRRGGBB: A string containing a HEX color code.
    • RGBA, RRGGBBAA, 0xRGBA, 0xRRGGBBAA: A string containing a HEX color code and alpha channel.
  • secondary-color: Changes the icon's secondary color. Specified in the same format as color.
  • tertiary-color: Changes the icon's tertiary color. Specified in the same format as color.
  • opacity: Defines the relative transparency of the object. Set as a real number. Works as scale for alpha: doesn't change the value but multiplies it by the color's existing alpha value. If you need to change the alpha value, set the color using the color property.
  • scale: Changes the scale of the object. Set as a real number. The size of the object is multiplied by scale.

Examples

The example below shows how to make the geometry of all water objects transparent.

https://static.api.mappable.world/v1?lang=en_US&ll=28.97709,41.005233&z=15&style=tags.all:water|elements:geometry|stylers.opacity:0&apikey=YOUR_API_KEY

The example below shows how to change the label color of all POI and public transport network nodes.

https://static.api.mappable.world/v1?lang=en_US&ll=28.97709,41.005233&z=15&style=tags.any:poi;transit_location|elements:label.text.fill|stylers.color:DD0000&apikey=YOUR_API_KEY

The example below shows how to change the color of all elements of all POI, urban blocks and public spaces, which are not parks.

https://static.api.mappable.world/v1?lang=en_US&ll=28.871673,40.997763&z=17&style=types:polygon|tags.any:admin;urban_area;poi|tags.none:park|stylers.color:f9f7aa&apikey=YOUR_API_KEY

The example below shows how to change the geometry color of all roads in the zoom range from 13 to 20, and make them more transparent in the zoom range from 17 to 22.

https://static.api.mappable.world/v1?lang=en_US&ll=28.871673,40.997763&z=17&style=tags.any:road|elements:geometry|stylers[13-20].color:58e3e2|stylers[17-22].opacity:0.2&apikey=YOUR_API_KEY

The example below shows how to disable all polygons, remove the direction icon on roads and change the lightness and saturation of all POI.

https://static.api.mappable.world/v1?lang=en_US&ll=28.97709,41.005233&z=12&style=elements:geometry|stylers.hue:0d69f2~elements:label.icon|stylers.hue:0d69f2~elements:label.text.fill|stylers.color:083f91&apikey=YOUR_API_KEY

Previous
Scaling map objects
Next
Map theme