JSON reference for cloud-based maps styling

Select platform: Android iOS JavaScript Web Service

The JSON schema for cloud-based maps styling lets you use JSON to customize maps just as you would through the style editor interface. This document describes the JSON schema and how to make JSON style declarations.

Download the JSON schema

To learn how to edit a map style using JSON within the style editor, or to import and export a map style, see Use JSON with cloud-based maps styling.

See an example JSON style declaration

The following JSON style declaration sets a background color, and then defines styles for points of interest, parks, water features, and hides labels for food and drink locations.


{
  "variant": "light",
  "styles": [
    {
      "id": "natural.land",
      "geometry": {
        "fillColor": "#f7e3f7"
      }
    },
    {
      "id": "natural.water",
      "geometry": {
        "fillColor": "#d4b2ff"
      },
      "label": {
        "textFillColor": "#3d2163",
        "textStrokeColor": "#f0e1ff"
      }
    },
    {
      "id": "pointOfInterest",
      "label": {
        "pinFillColor": "#e0349a",
        "textFillColor": "#a11e6e",
        "textStrokeColor": "#ffd9f0"
      }
    },
    {
      "id": "pointOfInterest.emergency.hospital",
      "geometry": {
        "fillColor": "#ffe3e3"
      }
    },
    {
      "id": "pointOfInterest.foodAndDrink",
      "label": {
        "visible": false
      }
    },
    {
      "id": "pointOfInterest.recreation.park",
      "geometry": {
        "fillColor": "#f9b9d2"
      }
    }
  ]
}

The JSON object

A JSON style declaration consists of a top-level object and an array of style rules.

Top-level settings (optional) - Global style settings like backgroundColor and variant.
styles - An array of style rule objects, which can consist of the following:
- id - The map feature to select for this style modification (e.g., pointOfInterest.recreation.park).
- geometry (optional) - The geometric elements of the map feature and the style rules to apply (e.g., fillColor).
- label (optional) - The text or pin label of the map feature and the style rules to apply (e.g., textStrokeColor).

Top-level settings

The properties in the following table apply to the entire map style.

Property	Type	Description	Example
`backgroundColor`	String	Customize the background color of the map app using a #RRGGBB hex string. This setting does not support changes to the opacity.	"#002211"
`variant`	"light"\|"dark"	Specify light or dark mode. If unspecified, the default is "light".	"light"
`monochrome`	boolean	To enable monochrome, use `true` for a gray version of the map.	`true`

Style rule objects

This section describes the properties that define the style rule objects in the styles array to customize map features. Each style rule object must consist of the following:

id property.
geometry or label element with the associated styler properties defined.

`id` (map feature)

The id property specifies the map feature to style. The property names are camelcase versions of the map feature names in the style editor.

The map features form a category tree. If you specify a parent feature type, such as pointOfInterest, the styles you specify for the parent apply to all its children, such as pointOfInterest.retail and pointOfInterest.lodging. For details, see Map feature hierarchy.

List of available `id` properties

The available id properties are as follows:

pointOfInterest
pointOfInterest.emergency
pointOfInterest.emergency.fire
pointOfInterest.emergency.hospital
pointOfInterest.emergency.pharmacy
pointOfInterest.emergency.police
pointOfInterest.entertainment
pointOfInterest.entertainment.arts
pointOfInterest.entertainment.casino
pointOfInterest.entertainment.cinema
pointOfInterest.entertainment.historic
pointOfInterest.entertainment.museum
pointOfInterest.entertainment.themePark
pointOfInterest.entertainment.touristAttraction
pointOfInterest.foodAndDrink
pointOfInterest.foodAndDrink.bar
pointOfInterest.foodAndDrink.cafe
pointOfInterest.foodAndDrink.restaurant
pointOfInterest.foodAndDrink.winery
pointOfInterest.landmark
pointOfInterest.lodging
pointOfInterest.recreation
pointOfInterest.recreation.beach
pointOfInterest.recreation.boating
pointOfInterest.recreation.fishing
pointOfInterest.recreation.golfCourse
pointOfInterest.recreation.hotSpring
pointOfInterest.recreation.natureReserve
pointOfInterest.recreation.park
pointOfInterest.recreation.peak
pointOfInterest.recreation.sportsComplex
pointOfInterest.recreation.sportsField
pointOfInterest.recreation.trailhead
pointOfInterest.recreation.zoo
pointOfInterest.retail
pointOfInterest.retail.grocery
pointOfInterest.retail.shopping
pointOfInterest.service
pointOfInterest.service.atm
pointOfInterest.service.bank
pointOfInterest.service.carRental
pointOfInterest.service.evCharging
pointOfInterest.service.gasStation
pointOfInterest.service.parkingLot
pointOfInterest.service.postOffice
pointOfInterest.service.restStop
pointOfInterest.service.restroom
pointOfInterest.transit
pointOfInterest.transit.airport
pointOfInterest.other
pointOfInterest.other.bridge
pointOfInterest.other.cemetery
pointOfInterest.other.government
pointOfInterest.other.library
pointOfInterest.other.military
pointOfInterest.other.placeOfWorship
pointOfInterest.other.school
pointOfInterest.other.townSquare
political
political.countryOrRegion
political.border
political.reservation
political.stateOrProvince
political.city
political.sublocality
political.neighborhood
political.landParcel
infrastructure
infrastructure.building
infrastructure.building.commercial
infrastructure.businessCorridor
infrastructure.roadNetwork
infrastructure.roadNetwork.noTraffic
infrastructure.roadNetwork.noTraffic.pedestrianMall
infrastructure.roadNetwork.noTraffic.trail
infrastructure.roadNetwork.noTraffic.trail.paved
infrastructure.roadNetwork.noTraffic.trail.unpaved
infrastructure.roadNetwork.parkingAisle
infrastructure.roadNetwork.ramp
infrastructure.roadNetwork.road
infrastructure.roadNetwork.road.arterial
infrastructure.roadNetwork.road.highway
infrastructure.roadNetwork.road.local
infrastructure.roadNetwork.road.noOutlet
infrastructure.roadNetwork.roadShield
infrastructure.roadNetwork.roadSign
infrastructure.roadNetwork.roadDetail
infrastructure.roadNetwork.roadDetail.surface
infrastructure.roadNetwork.roadDetail.crosswalk
infrastructure.roadNetwork.roadDetail.sidewalk
infrastructure.roadNetwork.roadDetail.intersection
infrastructure.railwayTrack
infrastructure.railwayTrack.commercial
infrastructure.railwayTrack.commuter
infrastructure.transitStation
infrastructure.transitStation.bicycleShare
infrastructure.transitStation.busStation
infrastructure.transitStation.ferryTerminal
infrastructure.transitStation.funicularStation
infrastructure.transitStation.gondolaStation
infrastructure.transitStation.monorail
infrastructure.transitStation.railStation
infrastructure.transitStation.railStation.subwayStation
infrastructure.transitStation.railStation.tramStation
infrastructure.urbanArea
natural
natural.continent
natural.archipelago
natural.island
natural.land
natural.land.landCover
natural.land.landCover.crops
natural.land.landCover.dryCrops
natural.land.landCover.forest
natural.land.landCover.ice
natural.land.landCover.sand
natural.land.landCover.shrub
natural.land.landCover.tundra
natural.water
natural.water.ocean
natural.water.lake
natural.water.river
natural.water.other
natural.base

Elements

Elements are subdivisions of a map feature. For example, a road consists of the graphical line (the geometry) on the map, and also the text denoting its name (the label).

The following elements are available, but note that a specific map feature may support none, some, or all, of the elements:

geometry: Selects all the geometric elements (e.g., polygon, polyline) of the specified map feature.
label: Selects all the label elements (e.g., text, pin) of the specified map feature.

Stylers

Stylers are how you define your style rules for each element of a map feature.

For example, for a building footprint you can style each element as follows:

Example `geometry` stylers for a building	Example `label` stylers for a building
Whether to hide or show the building footprint polygon on the map.	Whether to hide or show the building label.
Polygon fill color and opacity.	Text fill color and opacity.
Border color, opacity, and width.	Text stroke color and opacity.

This section describes the different style options available for the geometry and label elements.

`geometry` stylers

The following table lists all the available geometric stylers.

Styler	Type	Description
`visible`	boolean	To hide the polygon or polyline of a map feature, set to `false`.
`fillColor`	string	Customize the color of the polygon or polyline with an RGB hex string.
`fillOpacity`	float	Customize the opacity of the polygon or polyline, where 0 is transparent and 1 is opaque.
`strokeColor`	string	Customize the color of the outline with an RGB hex string.
`strokeOpacity`	float	Customize the opacity of the outline, where 0 is transparent and 1 is opaque.
`strokeWeight`	float	Customize the thickness of the outline from a range of 0 to 8.

For more information, see Polygons and Polylines.

`label` stylers

The following table lists all the available label stylers.

Styler	Type	Description
`visible`	boolean	To hide the label of a map feature, set to `false`.
`textFillColor`	string	Customize the color of the text label with an RGB hex string.
`textFillOpacity`	float	Customize the opacity of the text label, where 0 is transparent and 1 is opaque.
`textStrokeColor`	string	Customize the color of the outline with an RGB hex string.
`textStrokeOpacity`	float	Customize the opacity of the outline, where 0 is transparent and 1 is opaque.
`textStrokeWeight`	float	Customize the thickness of the outline from a range of 0 to 8.
`pinFillColor`	string	Customize the pin color with an RGB hex string.

For more information, see Icons and text labels.

Keyzooms

You can set a single style for a feature for all keyzoom levels or specify different styles for different keyzoom levels. If you only provide one style, it will be used for all keyzoom levels starting from z0. If you provide styles for different keyzoom levels, the style will apply from that zoom level until the next one you've defined.

To set a keyzoom level for a style, in the styler property, define the keyzoom level from z0 to z22 and then the styler customization.

In the following example, the color of water is black from keyzoom levels 0-5, dark gray from keyzoom levels 6-11, and light gray starting from keyzoom level 12.

{
  "id": "natural.water",
  "geometry": {
    "fillColor": {
      "z0": "#000000",
      "z6": "#666666",
      "z12": "#cccccc"
    }
  }
}

For more information, see Style zoom levels.