Layers

A layer group contains a list of layers. Each layer group must include at least one layer, and the order at the layer level specifies how layers are organized within their group. Each layer must also include a unique layer ID, url, label and type.

The table below outlines the value attribute pairs which can be defined for layers. Some layer types have additional fields which are mandatory.

Property	Explanation	Data type	Example
id	Unique layer id	string	`"id": "GLAD",`
order	Controls the ordering othe	string	`"order": 2,`
type	Type of layer The following layer types are currently supported tiled webtiled image dynamic feature wms remoteDataLayer	string	`"type": "dynamic",`
label	Contains a list of label objects	Label Objects	`"label": {"en": "Protected Areas","fr": "Zones protégées","sp": "Áreas protegidas"},`
Url	Url for the service	string	`"url": "https://gis-gfw.wri.org/arcgis/rest/services/forest_change/MapServer",`
opacity (optional)	specifies the transparency of the layer upon load,value may range range from 0 to 1. If this value is not specified then the default is	numeric	`"opacity":0.5,`
Technical Name (optional)	Technical name for the GFW Metadata API	string	`"technicalName": "tree_cover",`
Visible (optional)	Indicates if layer is visible when application opens, if the value is not specified the default is false	boolean	`"visible": true,`
LegendLayer (optional)	Layer id for an extra legend on GFW server, used to replace standard legends or add legends to layer which do not have one.	List	`"legendLayer": [0],`
PortalItemId (optional)	Item id is used to bring in metadata via a created ArcGIS Online hosted feature layer or tile layer. If included, it will insert a itemId to the metadata query and then populate the information modal with the corresponding values	string	`"portalItemId": "a0eb6a461c0e43e0a1019a26d6d46076"`,`
Popup (optional)	Specifies the attributes will appear in the data tab when a user clicks on a polygon. Do not include if the layer does not need a popup	Title list and Content list	See popup page,
Dashboard Icon (optional)	Adds an icon to the left of the 'i' icon to a layer in the layer panel. Clicking this icon directs to an external analysis dashboard or other site containing additional information about the corresponding layer.	string	See dashboard icon page

Layer Types

Tiled: A tile layer is a cached ESRI MapService layer, either hosted on ArcGIS Online or ArcGIS Enterprise.

Webtiled: Layer hosted as webtiles in z/x/y format, typically hosted in an AWS S3 bucket

Image: Layers which are hosted on an Image Server

Dynamic: Layers which are hosted on an Map Server, typically ESRI map image services

Feature: layers which are hosted as feature services

wms: Layers hosted as web map servrices (wms) typically on a Geoserver or Mapserver

remoteDataLayer: This data layer is managed through the Resource Watch API, https://resource-watch.github.io/doc-api/reference.html#resource-watch-api-reference. Resource Watch data layers such as Tree Cover Loss, GLAD Alerts, and Intact Forest Landscapes are centrally managed by the Resource Watch and Mapbuilder team through the Resource Watch API.

Additional Parameters for specific layer types

For some layer types the user has the option to specify additional parameters in order to further customize the application. These parameters are specified below:

RemoteDataLayer

Here is the process to add a Remote data layer to the Resource Watch API:

Create a RW account for the user here. This will send verification link to the registered email. The email will come from Okta - the third party auth service we use.
Once verified, use the email and password to login via the API using this doc. The response will have the token.
Add apps (platforms the layers and other resources will be used in) using this doc. The doc has example requests with app values to use.
You will need to make sure you have the MANAGER role to the the forest-atlas application by sending a request to [email protected]
Once you have privileges you can generate a token by going to https://api.resourcewatch.org/auth/generate-token
You will now be able to use your token to create data layers. Refer to https://resource-watch.github.io/doc-api/reference.html#resource-watch-api-reference when creating a data layer. Highly recommend using Postman to manage your data layers, https://www.postman.com/.
Once your data layer is created it will generate a uuid that you will need for the configuration below. Here is an example of a created data layer the id property is what you will use as the uuid, https://production-api.globalforestwatch.org/v1/dataset/4f633c1b-af4c-435a-af01-4bba913f5041/layer/356f862b-3e70-493a-997b-dc2a193410e9.

Another option, if the steps above do not fit your need, you can reach out to someone on the Mapbuilder team at [email protected] to request that a data layer be added to the Resource Watch API.

Here is an example of a Remote data layers being added to the config file, users have the option to turn on layers by default and adjust the default opacity. For example, the following configuration would turn on the loss layer by default and set the opacity to 0.7.

{
"visible": true,
"opacity":0.8,
"id": "TREE_COVER_LOSS",
"order": 1,
"type": "remoteDataLayer",
"uuid": "2aed67b3-3643-40d3-9c1e-8af9afb5d9e2"
}

Dynamic Layer Type

Property	Explanation	Data type	Example
LayerIDs	List of layers from the service to include in the mapbuilder layer	List	`"layerIds": [1,2],`
filterField (optional)	An optional list of fields used to add a filter for a specific field to the layer. Supports using different fields for different languages. Click here for more details on adding filters.	List of filters fields	`"filterField": {"en":"Category_EN","ka":"Category_KA"}`
filterField (optional)	An optional list of labels for the filter. Supports using different fields for different languages. Click here for more details on adding filter	List of filters labels	`"filterLabel": {"en": "Filter by Category","ka": "Filter by Category"}`

Webtiled Layer Type

Property	Explanation	Data type	Example
subDomains (optional)	Subdomains webtile URL to load balance requests. Ie https://{subdomain}.url.com/webtiles/{z}/{x}/{y}	List	`"subDomains": [0,1,2,3],`

Image Layer Type

Property	Explanation	Data type	Example
Colormap (optional)	Overwrites the rendering rule for colormap raster function of an image service	List	"colormap": `[[1,0,179,0]],`

WMS

Property	Explanation	Data type	Example
layerName	The name of the layer from the WMS service to include	string	`"layerName": "topp:states"`

Sample layer configurations:

The examples below show how to configure some common layer types. The examples below do not include popups. Consult the popup section for documentation on how to add a popup to your layers. Popup can only be added to vector layers, typically hosted through feature services, dynamic services, or WMS services.

Feature Service

In this example we create a layer called "RSPO Oil Palm Concession" and have specified labels in English and French. The layer will be the first layer in the group. There is no popup configured for this layer. Consult the popup section for additional information on how to configure a popup to show the layers attributes.

{
         "order": 1,
		"id": "OilPalm",
      "type": "feature",
      "url": "https://services3.arcgis.com/mKcWKyEU5Tl36xeT/arcgis/rest/services/RSPO_Oil_Palm_Concession_(Sept_2018)/FeatureServer/0",
		"label":{
			"en":"RSPO Oil Palm Concession",
                        "fr":"Concession de palmier à huile RSPO"
       }
}

Dynamic Service

In this example, we add a layer called Touristic Routes of Protected Areas. The type is dynamic since the layers is hosted on a MapServer. We have specified a layerID of one because the layer is the second layer in the service. In ArcGIS MapServices the first layer will have a layerID of 0. The layer is the second layer in the group.

{
	"order": 2,
	"id": "PARoads",
	"type": "dynamic",
	"url": "https://gis.mepa.gov.ge/server/rest/services/atlas/protected_areas/MapServer",
	"layerIds": [1],
	"label": {
		"en": "Touristic Routes of Protected Areas",
		"fr": "Routes touristiques des aires protégées"}
				}

Tile

In this example we configure a tiled service for Global wetlands provided by CIFOR. The layer is the third layer in the group.

{
        "order": 3,
		"id": "WorldEcosystems",
        "type": "tiled",
        "url": "https://tiles.arcgis.com/tiles/P3ePLMYs2RVChkJx/arcgis/rest/services/World_Ecosystems/MapServer",
		"layerIds": [0],
		"label":{
			"en":"World Ecosystems",
                        "fr":"Écosystèmes mondiaux"
      }}

WMS

In this example we configure a WMS service showing the boundaries of the United States.

{
        "order": 4,
        "id": "WMS_STATES",
        "type": "wms",
        "url": "https://ahocevar.com/geoserver/wms",
        "layerName": "topp:states",
        "visible": true,
        "label": {
          "en": "States"
        }
      }

Webtiled Layer

{
	"order": 5,
	"technicalName": "global_landcover",
	"url": "https://wri-tiles.s3.amazonaws.com/global-landcover/{level}/{col}/{row}.png",
	"type": "webtiled",
	"id": "LAND_COVER",
	"label": {
		"en": "Land Cover"
		},
	"sublabel": {
		"en": "(2009, global, globecover – ESA/ UCLouvain)"
		}
		}

Creating a layer group.

Below we can see how the layers specified above can be merged into a single layer group called my example layer group.

"GROUP_Example": {
			"order": 1,
			"label": {
				"en": "My Example layer group",
				"fr": "Mon groupe de couches d'exemple"
			},
"layers": [{
	"order": 1,
	"id": "OilPalm",
	"type": "feature",
	"url": "https://services3.arcgis.com/mKcWKyEU5Tl36xeT/arcgis/rest/services/RSPO_Oil_Palm_Concession_(Sept_2018)/FeatureServer/0",
	"label": {
		"en": "RSPO Oil Palm Concession",
		"fr": "Concession de palmier à huile RSPO"
	}
},
{
	"order": 2,
	"id": "PARoads",
	"type": "dynamic",
	"url": "https://gis.mepa.gov.ge/server/rest/services/atlas/protected_areas/MapServer",
	"layerIds": [1],
	"label": {
		"en": "Touristic Routes of Protected Areas",
		"fr": "Routes touristiques des aires protégées"
	}
},
{
	"order": 3,
	"id": "Globalwetlands",
	"type": "tiled",
	"url": "https://tiles.arcgis.com/tiles/P8Cok4qAP1sTVE59/arcgis/rest/services/World_Wetland_2016_CIFOR/MapServer",
	"layerIds": [0],
	"label": {
		"en": "Global Wetlands (CIFOR, 2016)",
		"fr": "Zones humides globales (CIFOR, 2016)"
	}
},
{
        "order": 4,
        "id": "WMS_STATES",
        "type": "wms",
        "url": "https://ahocevar.com/geoserver/wms",
        "layerName": "topp:states",
        "visible": true,
        "label": {
          "en": "States"
        }
      }]
}

Layer Filtering:

Mapbuilder has an option to expose an attribute and let users filter based on the unique fields in the attribute table. This option is currently only available for dynamic and feature layers. Below is a screenshot of what this might look like in a mapbuilder application. In this mapbuilder, users are able to filter the protected area layer based on the type of protected area.

The configuration below shows an example how to add a filter to dynamic and feature layers. The filterField parameter specifies the field name of the field to filter while, the filterlabel indicates the label for the filter. Both fields are a list and support multiple languages.

Dynamic

In the example below a filter is added to the Protected Area layer and the user is able to filter based on the protected area type. The filter is configured to support two different languages.

{
        "order": 5,
        "id": "PA",
        "type": "dynamic",
        "visible": true,
        "url": "https://gis.mepa.gov.ge/server/rest/services/atlas/protected_areas/MapServer",
        "layerIds": [
          4
        ],
        "label": {
          "en": "Protected Areas",
          "ka": "დაცული ტერიტორიები"
        },
        "filterField": {
          "en": "Category_EN",
          "ka": "Category_KA"
        },
        "filterLabel": {
          "en": "Filter by Category",
          "ka": "Filter by Category"
        }
		}

Layers Versions:

MapBuilder also supports adding a layer toggle which let's the user switch between different versions of a layer. Currently, this feature is only supported for layers with "type":"feature" or "type":"dynamic". An example of this is shown in the screenshot below:

In this example, the user can toggle between the two different feature layers, named recent alerts and All Alerts. This is done by specifying an array of layer versions for the layer. For a versioned layer the layer configuration must include:

id for the layer
type
Object of label listing labels in different languages
Object of versionHeaderText which lists the label for the layer version toggle in different languages
Array of layer versions.

The Array for each layer versions specify:

Object of label listing labels for layer in different languages
url
LayerID for versioned layers where the type is dynamic

An example configuration is shown below.

{
	"order": 2,
	"id": "PRIORITYALERTS",
	"type": "feature",
	"visible": true,
	"label": {
		"en": "Priortized Alert"
	},
	"versionHeaderText": {
		"en": "All Alerts/Recent Alerts"
	},
	"versions": [{
		"label": {
			"en": "Recent Alerts"
		},
		"url": "https://services2.arcgis.com/g8WusZB13b9OegfU/ArcGIS/rest/services/IDN_Siak_alerts_latest/FeatureServer/0"
	},
	{
		"label": {
			"en": "All Alerts"
		},
		"url": "https://services2.arcgis.com/g8WusZB13b9OegfU/ArcGIS/rest/services/IDN_Siak_alerts/FeatureServer/0"
	}]
}

Nested Layers:

The section below highlights how to configure nested layers, when you Layer group type is set to "groupType": "nested". The screenshot below shows an example of what a nested layer group will look like.

From the screenshot, we see that five layers are nested under the orthophotos group, while two layers are nested under Topopgrahic group. Each layer contains an array of nested layers. All layers included in the layer group must include nested layers. It is currently not possible to mix nested and non-nested layers in the same group.

For the layer, you must specify:

id
order. Specifies the order of layer within the layer group
Object of label listing labels in different languages

Each Layer should contain an array of nestedLayers. For each nestedLayer, specify a minimum of:

id
Object of label listing labels in different languages
order Specifies the order of layer within the nested layer group
type of layer

Below is an example of a configuration for a nested Layer group.

 "GROUP_Orth": {
    "groupType": "nested",
    "order": 8,
    "label": {
      "en": "Orthophotos/Topographic Maps"
    },
    "layers": [
      {
        "order": 1,
        "id": "ortho",
        "label": {
          "en": "Orthophotos"
        },
        "nestedLayers": [
          {
            "id": "Adjara",
            "order": 1,
            "type": "webtiled",
            "url": "http://mp1.napr.gov.ge/ORTHO_2015_ADJARA/wmts/ORTHO_2015_ADJARA/GLOBAL_MERCATOR/{level}/{col}/{row}.png",
            "label": {
              "en": "2015 Adjara"
            }
          },
          {
            "id": "Samegrelo",
            "order": 2,
            "type": "webtiled",
            "url": "http://mp1.napr.gov.ge/ORTHO_2015_SAMEGRELO/wmts/ORTHO_2015_SAMEGRELO/GLOBAL_MERCATOR/{level}/{col}/{row}.png",
            "label": {
              "en": "2015 Samegrelo"
            }
          },
          {
            "id": "Vere",
            "order": 3,
            "type": "webtiled",
            "url": "http://mp1.napr.gov.ge/ORTHO_2015_VERE/wmts/ORTHO_2015_VERE/GLOBAL_MERCATOR/{level}/{col}/{row}.png",
            "label": {
              "en": "2015 Vere"
            }
          },
          {
            "id": "Norv",
            "order": 4,
            "type": "webtiled",
            "url": "http://mp1.napr.gov.ge/ORTHO_2016-17_NORV/wmts/ORTHO_2016-17_NORV/GLOBAL_MERCATOR/{level}/{col}/{row}.png",
            "label": {
              "en": "2016-17 Norv"
            }
          },
          {
            "id": "Dasavleti",
            "order": 5,
            "type": "webtiled",
            "url": "http://mp1.napr.gov.ge/ORTHO_2014_DASAVLETI/wmts/ORTHO_2014_DASAVLETI/GLOBAL_MERCATOR/{level}/{col}/{row}.png",
            "label": {
              "en": "2014 Dasavleti"
            }
          }
        ]
      },
      {
        "order": 2,
        "id": "topo",
        "label": {
          "en": "Topographic Maps"
        },
        "nestedLayers": [
          {
            "id": "Topo1000",
            "order": 1,
            "type": "webtiled",
            "url": "http://mp1.napr.gov.ge/TOPO_10k_1952_2007/wmts/TOPO_10000_1952_2007/GLOBAL_MERCATOR/{level}/{col}/{row}.png",
            "label": {
              "en": "TOPO 10000 1952_2007"
            }
          },
          {
            "id": "TOPO50000",
            "order": 1,
            "type": "webtiled",
            "url": "http://mp1.napr.gov.ge/TOPO_50k_GEO_2007/wmts/TOPO_50000_GEO_2007/GLOBAL_MERCATOR/{level}/{col}/{row}.png",
            "label": {
              "en": "TOPO 50000 GEO_2007"
            }
          }
        ]
      }
    ]
  }

Layer Metadata:

Webmap groups

For layers which come from the webmap group the following logic is used:

Full extended metadata from ArcGIS Online is used if the metadata is defined in ArcGIS Online for your item (https://doc.arcgis.com/en/arcgis-online/manage-data/metadata.htm)
If extended metadata is not defined, then the description and summary will be used instead
If the layer added is an ArcGIS Feature Service or MapService and the service was added to the map via a url, the metadata from the itself layer will be used.

Non-Webmap groups

For layers which are configured through the configuration, the following logic is used:

If the Technical name for a layer is specified then the metadata for the layer will be pulled from the GFW Metdata API Coordinate with the GFW team to obtain access to the form for adding metadata to the GFW Metadata API
If the layer is stored in the API, and includes a metadata url the source used will be the metadata
If the technical name is not specified and the data is hosted through ArcGIS (Feature of MapService Layer) metadata from the layer will be used. Make sure your layer includes metadata before you publish it

Using extralayers layer group:

Layer group extraLayers accepts an array of layer objects that follow established config requirements. Any dynamic or feature layer is accepted in this group. Any layer added to this group will not be visible in the left layer panel, will not be visible in the legend, and will not be queryable. This can be beneficial if you have a dataset you would like to include but you do not want it to be toggled on/off in left panel or appear in the legend.

To use a specific country mask, you use the layer object config in the example below. ISO code for the country should also be specified in config (see Plain Attributes).

      {
        id: 'MASK',
        type: 'dynamic',
        order: 10000,
        url:
          'https://gis.forest-atlas.org/server/rest/services/country_masks/country_mask_global/MapServer',
        opacity: 0.35,
        layerIds: [0]
      },

Home
Deployment
Configuration

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Layers

Layers

Layer Types

Additional Parameters for specific layer types

RemoteDataLayer

Dynamic Layer Type

Webtiled Layer Type

Image Layer Type

WMS

Sample layer configurations:

Feature Service

Dynamic Service

Tile

WMS

Webtiled Layer

Creating a layer group.

Layer Filtering:

Dynamic

Layers Versions:

Nested Layers:

Layer Metadata:

Webmap groups

Non-Webmap groups

Using extralayers layer group:

Clone this wiki locally