Skip to content

Appendix D: mapViews Field

This appendix provides a detailed description of the "mapViews" field, a field used to define the mapParameters field which is one of the fields used to define each of the Formbird components below:

1 Purpose

The "mapViews" field is an array of map view definitions. each defining the properties of a map view.

  • A map view is a 2D image of an area of the earth's surface. For example:
    • Satellite view displays a satellite photo of an area.
    • Map view displays the streets of an area.
  • Each map view definition is a set of name/value pair fields, some required, some optional.

2 Definition

The tables below list and describe the name/value pair fields used to define the properties of a map view.

Note:

  1. Default values for the fields described in the tables below are shown in bold text.

2.1 Required Customizable Fields

Field Valid Values Description
params Array of map view parameters Array of parameters defining how a map view is to be displayed.
Section 2.3 params Field lists and describes the "params" field parameters .
uiLabel Any character Defines the button label for a map view or a grouping of map views. Clicking a button will display the map in accordance with its associated map view definition or group map view definition.

Example:
"uiLabel": "V"
url url address to communicate with a particular geoserver for geospatial data.
Vicmap url Vicmap geoserver for geospatial data.

Example:
"url": "https://base.maps.vic.gov.au/service"
OSM url Formbird geoserver for Open Street Map (OSM) geospatial data.

Example:
"url": "https://osm.formbird.com/tiles/{z}/{x}/{y}.png"1

2.2 Optional Customizable Fields

Field Valid Values Description
apiKey Valid API key Your API key, if required by the map server.
Map servers are used to share geospatial data. Examples of map servers are Google and Geoserver.

Example:
"apiKey": "your API key"
crossOrigin Used for loaded images.
Note: A crossOrigin value is required if using the WebGL renderer or if accessing pixel data from an image server.
It's a way for the webpage to ask the image server for permission to use the image.
User credentials Asks for permission, sending user credentials to the server.

Example:
"CrossOrigin" : "jsmith.j53p19f5"
anonymous Asks for permission but don't send extra information.

Example:
"crossOrigin": anonymous
null Default value. Do not ask for permission.

Example:
"crossOrigin": null
EPSG Valid EPSG SRID EPSG is a spatial coordinate system used to locate geographical entities on a map, a map being a 2D projection of the 3D earth's surface or a region of the earth's 3D surface. There are many 2D projections, each using different properties to represent distances, angles or areas. Certain projections are better suited for different regions in the world.
An EPSG SRID (Spatial Reference System Identifier) value identifies a specific 2D projection coordinate system together with the region of the earth it covers. E.g. EPSG:3111 is the projection coordinate system used for rendering map of the state of Victoria (between 140.9500, -39.1500 and 149.9800, -34.0000).

Example:
"EPSG": "EPSG:3111"
EPSG:3857 Defaults to the Web Mercator projection (EPSG:3857) which is used to render a map of the world (between 85.06°S and 85.06°N) in Google Maps, OpenStreetMaps, OpenLayers, etc.
groupView Array of map view definitions A groupView field groups multiple map views together for display purposes. When map views are grouped, the uiLabel field is defined at the group level.
isShow true Identifies the initial map view to show on load.

Example:
"isShow": true
Defaults to the the first map view defined in the map views array.
serverType Defines the map source.
geoserver An open source server for sharing geospatial data. Used for web based maps such as OpenLayers and Bing Maps.

Example:
"serverType": "geoserver"
tile A server providing a map as a set of square tiles (images) arranged in a grid. When a map moves to a new location, or to a new zoom level, the Map API determines which tiles are needed and translates that information into a set of tiles to retrieve from the server.

Example:
"serverType": "tile"
google Defaults to the google server for the source of geospatial data.

2.3 params Field

The "params" field in Section 2.1 Required Customizable Fields is an array of parameters defining how a map view is to be displayed.

The table below lists and describes the "params" field parameters.

Parameter Description
BBOX Specifies the portion of the Earth to be mapped by specifying the the coordinates of the bounding box corners (lower left, upper right) in the units defined by the SRS field value.

Example:
"BBOX": "16446787.78408,-4393099.8016821,16759873.851936,-4080013.733826",
FIRSTTILE
Valid Values: true, false

Example:
"FIRSTTILE": true
FORMAT Specifies the output format of the response to the request.

Valid Values: Dependent on the formats supported by the Map Server and the request operation being invoked.

Example:
"FORMAT": "image/png"
HEIGHT Height in integer pixels of the map image to be produced i.e. the number of pixels to be used between the minimum and maximum y values (inclusive) in the BBOX. In the case where the aspect ratio of the BBOX and the ratio WIDTH/HEIGHT values are different, the WMS will stretch the returned map so that the resulting pixels are rendered in the aspect ratio of the BBOX.

Example:
"HEIGHT": "512",
LAYERS Specifies the map view layer to be returned by the request.

Examples:
1. Vicmap, Web Mercator, cartographic.
"LAYERS": "CARTO_WM"

2. Vicmap, Web Mercator, aerial.
"LAYERS": "AERIAL_WM"

3. Vicmap, Web Mercator, overlay.
"LAYERS": "CARTO_OVERLAY_WM"
REQUEST Specifies which service operation is being invoked. The value shall be the name of one of the operations offered by the map service.

Valid Values: Dependent on the Map Service.

Examples:
"request": "GetMap" - returns a map image.
"request": "GetCapabilities" - returns parameters about the WMS (e.g. map image format and WMS version compatibility) and the available layers (e.g. map bounding box, coordinate reference systems).
SERVICE The Map Service protocol.

Examples:
"service": "WMS" - WMS (Web Map Service) is a standard protocol developed by the Open Geospatial Consortium for serving geospatial map images over the Internet. These images are typically produced by a map server from data provided by a GIS database.
SRS Specifies which Spatial Reference System applies to values in the BBOX parameter.
Examples:
"SRS": "EPSG:3857"
STYLES Specifies the rendering style of the map layer.

Example:
"STYLES": "" - To request the default style, use the null value i.e. ""
VERSION Specifies the Map Service protocol version number. The version number contains three non-negative integers, separated by decimal points, in the form “x.y.z”.
WIDTH Width in integer pixels of the map image to be produced i.e. the number of pixels to be used between the minimum and maximum y values (inclusive) in the BBOX parameter. In the case where the aspect ratio of the BBOX and the ratio WIDTH/HEIGHT values are different, the WMS will stretch the returned map so that the resulting pixels are rendered in the aspect ratio of the BBOX.

Example:
"WIDTH": "512",

3 Example

A "mapViews" array containing 3 individual map views and 1 group map view.

        "mapViews": [
            {
                "EPSG": "EPSG:3857",
                "isShow": true,
                "params": {
                    "BBOX": "16133701.716224,-4393099.8016821,16446787.78408,-4080013.733826",
                    "FIRSTTILE": true,
                    "FORMAT": "image/png",
                    "HEIGHT": "512",
                    "LAYERS": "CARTO_WM",
                    "REQUEST": "GetMap",
                    "SERVICE": "WMS",
                    "SRS": "EPSG:3857",
                    "STYLES": "",
                    "VERSION": "1.1.1",
                    "WIDTH": "512"
                },
                "serverType": "geoserver",
                "uiLabel": "V",
                "url": "https://base.maps.vic.gov.au/service"
            },
            {
                "EPSG": "EPSG:3857",
                "params": {
                    "BBOX": "16280475.531304,-4696291.0150527,16593561.59916,-4383204.9471967",
                    "FIRSTTILE": true,
                    "FORMAT": "image/png",
                    "HEIGHT": "512",
                    "LAYERS": "AERIAL_WM",
                    "REQUEST": "GetMap",
                    "SERVICE": "WMS",
                    "SRS": "EPSG:3857",
                    "STYLES": "",
                    "VERSION": "1.1.1",
                    "WIDTH": "512"
                },
                "serverType": "geoserver",
                "url": "https://base.maps.vic.gov.au/service",
                "uiLabel": "S"
            },
            {
                "crossOrigin": null,
                "serverType": "tile",
                "uiLabel": "O",
                "url": "https://osm.formbird.com/tiles/{z}/{x}/{y}.png"
            },
            {
                "groupView": [
                    {
                        "EPSG": "EPSG:3857",
                        "params": {
                            "BBOX": "16280475.531304,-4696291.0150527,16593561.59916,-4383204.9471967",
                            "FIRSTTILE": true,
                            "FORMAT": "image/png",
                            "HEIGHT": "512",
                            "LAYERS": "AERIAL_WM",
                            "REQUEST": "GetMap",
                            "SERVICE": "WMS",
                            "SRS": "EPSG:3857",
                            "STYLES": "",
                            "VERSION": "1.1.1",
                            "WIDTH": "512"
                        },
                        "serverType": "geoserver",
                        "url": "https://base.maps.vic.gov.au/service"
                    },
                    {
                        "EPSG": "EPSG:3857",
                        "params": {
                            "BBOX": "16446787.78408,-4393099.8016821,16759873.851936,-4080013.733826",
                            "FIRSTTILE": true,
                            "FORMAT": "image/png",
                            "HEIGHT": "512",
                            "LAYERS": "CARTO_OVERLAY_WM",
                            "REQUEST": "GetMap",
                            "SERVICE": "WMS",
                            "SRS": "EPSG:3857",
                            "STYLES": "",
                            "VERSION": "1.1.1",
                            "WIDTH": "512"
                        },
                        "serverType": "geoserver",
                        "url": "https://base.maps.vic.gov.au/service"
                    }
                ],
                "uiLabel": "M"
            }
        ]