Using the services - Developers

In OpenLayers

OpenLayers is a pure JavaScript library which allows dynamic maps to be added to any web page. The best way to learn how to use our services within OpenLayers is by studying one of our example OpenLayers map pages, which include commented code. A simple example which uses our cached services (WMS protocol) can be found here, or a WMTS example here. For using version 1.3.0 of the WMS with OpenLayers, check the code in our WMS version 1.3.0 example. The OpenLayers examples are also a great way to learn, along with the OpenLayers documentation.

Adding copyright layer

All of our WMS layers must always have the relevant copyright displayed on the maps.

By default, OpenLayers will request tiles, so in order for a map to have a single copyright appearing in the bottom left-hand corner of the map (and not on every tile), you need to specify the copyright layer is requested as a single tile. You also need to ensure that the user is unable to turn the copyright off via the 'displayInLayerSwitcher: false' parameter e.g.

var copyright = new OpenLayers.Layer.WMS("Copyright","",

{layers: "copyright", transparent: "true", format: "image/png"},

{isBaseLayer: false, singleTile: true, ratio: 1, displayInLayerSwitcher: false});

Alternatively, you can use the OpenLayers Attribution Control for the layer object e.g.

var contours = new OpenLayers.Layer.WMS("Contours","",

{layers: "contours", transparent: "true", format: "image/png"},

{isBaseLayer: false, attribution: "© Landcare Research 2017. Contains data sourced from LINZ. Crown Copyright Reserved"});

Using this method requires you to set the correct copyright for the layer you are using. These are given in the legal section.

In Google Maps (back to top)

The Google Maps API allows developers to add Google maps to their website. Landcare Research's (cached & uncached) WMS layers can be included in these maps relatively simply. All layers are available in Google Maps projection through our uncached WMS, however there is currently only limited support when you use our cached service. We hope to provide cached versions in Google Maps projection in the near future. The cached layers that are available can be accessed using the Google Maps XYZ Tile Service specification, an example of which can be found here.

Using the services - Desktop GIS

With ArcGIS (back to top)

The following steps describe an example of how to add a Landcare Research WMS layer / cached map tile service layer into ArcGIS. There are pros and cons to each type of service - for instance at small scale, maps requested through the uncached services will take longer to render. On the other hand, the straight WMS map rendering should be crisp at any scale, whereas as the cached services have been built at specific zoom levels: maps in between these specific zoom levels may render slightly fuzzily, or the text may be too small. We would recommend experimenting to see what form best suits your needs. These instructions were created using ArcGIS version 10.0, but should work using versions > 9.

  1. Open a new ArcGIS document, and set the Data Frame's coordinate system.
    • Right click on the 'Layers' in the Table of Contents
    • Choose 'Properties', then navigate to the 'Coordinate System' tab
    • In the 'Select a coordinate system' window at the bottom, expand the 'Predefined' folder, and navigate & choose: Predefined / Projected Coordinate Systems / National Grids / New Zealand / NZGD 2000 New Zealand Transverse Mercator
    • Click OK
  2. If you plan on using the cached map tiles, it might be worth loading in the set of predefined scales, at which the cached tiles should work best at. To do this:
    • Expand the scale dropdown menu and choose 'Customize This List' Scale Dropdown
    • Can then either create the list manually using the set of scales found in this textfile, alternatively you can download that textfile and choose the 'Load' option, then 'From File...' in the Scale Settings window, then navigate to the downloaded file, to load in the custom scale set.
    • If you go down this route be sure and check the 'Only display these scales when zooming' checkbox
    • Click OK to get back to the main map window
  3. Now the project is slightly more customized for your needs, you can now set up the connection(s) to the Web Map Services:

  4. Click the Add Data button ArcGIS Add Data Button
  5. Choose 'GIS Servers' from the 'Look in:' dropdown, then 'Add WMS Server'.
  6. In the window that appears, enter the URL for the desired service, cached or uncached. All these URLs can be found on the main page, however here are a few examples:
    • Cached maps that respond to WMS protocol:
    • LRI - WMS:
  7. Change the Version to '1.1.1' and click 'Get Layers'. The list of available layers should now be visible.
  8. ArcGIS Add WMS Window
  9. Click OK
  10. This will add the WMS to your available GIS Servers. It will be named slightly differently, dependent on the service, for example for the LRI, it will be 'Landcare Research NZ Land Resource Inventory on', or for the cached services: 'Landcare Research Public Cached Map Tile Service on'.
  11. The above steps are only required once per service. Once the WMS has been added it should appear in your 'GIS Servers' section next time you open ArcGIS.
  12. To load a specific layer, navigate to it by double clicking on the newly created WMS. You may have to double click on it additional times until you reach the list of available layers.
  13. ArcGIS Add WMS Navigate
  14. Then choose the desired layer by double clicking on it, or click and press the 'Add' button.
  15. ArcMap may display a 'Geographic Coordinate Systems Warning' message, it is safe to ignore this.

    ArcGIS Add WMS Layers
  16. If you are using our straight WMS, you can add a legend to the map by right clicking on the layer in the TOC, and choose 'Add WMS Legend To Map'.
  17. Our map services can of course be combined with any other data sources, however below are a couple of screenshots that use only LCR WMS layers in an ArcMap project. The layers are the topographic basemap, LCDB3 and a cartographic text layer. The second screenshot shows the layout view, using the legend provided by the WMS.
  18. ArcGIS Add WMS Layers ArcGIS Add WMS Layers

    Hints and Potential Issues

    • Additional documentation on using WMS within ArcGIS can be found here.
    • Use cached map services if draw speed is important, potentially at the expense of some clarity of the map images. Use the 'raw' WMS if map images are required to be sharp.
    • Rendering clarity issues are particularly noticeable on the cartographic text layer, for which we would recommend using the uncached, 'raw' WMS service.
    • We have implemented some layers so that a map won't display at certain zoom scales. This is to prevent our data being used at inappropriate scales. Our science layers usually won't display at scales larger than 1:25,000.
    • If no map is displayed, it may be due to incorrect projection settings or it may be that the request has timed out due to the volume of data requested. If this is the case, check the projection and try changing the scale to 1:500,000.
    • If you get a map back but the colours look strange, it may be due to ArcMap's Raster options. They can be accessed through the 'Customize' menu, under 'ArcMap Options' in the 'Raster' tab. The 'Default RGB Band Combinations' should be '1','2','3' for 'Red','Green','Blue' respectively.

    With Quantum GIS (back to top)

    Quantum GIS (QGIS) is an open source desktop GIS. The instructions below were created using QGIS 1.8.

    To add a WMS layer to QGIS:

    1. Open QGIS, and click the 'Add WMS Layer' button. QGIS Add Data Button
    2. From the resulting window, choose 'New' to create a new connection.
    3. QGIS Add Data
    4. Now enter the URL for the desired service, cached or uncached. If using the uncached WMS, you may have to specify the WMS version (e.g All the service URLs can be found on the main page, however here are a few examples:
      • Cached maps that respond to WMS protocol:
      • LRI - WMS:
      Add a Name for your connection, then click 'OK'.
    5. N.B. Using the WMTS protocol requires URL to be And if NZTM projection is desired, the 'Invert axis orientation' option needs to be checked.

      QGIS Add Data 2
    6. You can now connect to the service by clicking the 'Connect' button. From here you can then choose the layer to be added to the map. Once the desired layer has been highlighted make sure the correct projection is chosen. If it is incorrect, click on the 'Change...' button and change to the desired projection. For the uncached WMS, you can choose from the supported projections (e.g. 'NZGD2000 / New Zealand Transverse Mercator 2000'), Once chosen, click 'Add'.
    7. QGIS Add Data 3
    8. Step 3 is only required once per service. Once the WMS has been added it should remain in the drop down list of available connections in the 'Add Layer' window. Further layers can then be added to the map, taking care to choose the correct projection.
    9. For the best quality rendering, the WMS layers are recommended, especially for something like the cartographic text layer. This has the side effect of slow drawing maps at small scales. Maps will be rendered quicker the further you zoom in.
    10. Connecting to the cached layers is carried out in the same way, but using the cached services URL (e.g., HOWEVER layers must be added from the 'Tilesets' tab.
    11. QGIS Tilesets
    12. Additional documentation on how to use QGIS can be found here.

    WMS Legends in QGIS

    In order to display the associated legends, a QGIS plugin is required. Legends are only available through our uncached WMS (e.g.

    1. Installing the plugin is achieved via the 'Plugins' menu -> 'Fetch Python Plugins'
    2. From the resulting dialogue 'Options' tab, make sure the 'Allowed Plugins', 'Show all plugins, even those marked as experimental' option is checked.
    3. Move back to the Plugins tab, and search for 'CSI WMS Legend'.
    4. Highlight the plugin, and click 'Install plugin'
    5. The following button should now have appeared in the main QGIS window: QGIS WMS Legend
    6. Clicking this button should open a panel in the bottom left of QGIS. This is where the legend will appear. Clicking on a layer in the 'Layers' section should update the legend shown. N.B. Legends will only be shown for our uncached WMS. The plugin is currently only available for QGIS 1.8.
    7. QGIS with WMS legend

    Hints and Potential Issues

    • When using the cached service, it seems QGIS currently only lists a single projection per layer, which at the moment is NZTM. We are looking into possible solutions to this restriction.
    • Legends only available through our uncached WMS, and legend plugin only currently available for QGIS 1.8.

    With uDig desktop GIS (back to top)

    uDig is an open source desktop application framework, built with Eclipse Rich Client technology. Both our uncached & cached services work with uDig. However, for best quality rendering you need to change the default 'Basic WMS Renderer' format type order. This accessed from uDig preferences -> Rendering -> Basic WMS Render. Move image/png8 & image/png to the top. To add a layer:

    1. Open uDig, and from the 'Layer' menu choose 'Add...'.
    2. From the resulting window, choose either 'Web Map Server' (to use our uncached service) or 'Web Map Server Tile Cache (WMSC)' (to access our cached service). Then click 'Next'.
    3. uDig Add Data
    4. Now enter the URL for the desired service, e.g. for our uncached LRI WMS, the URL to enter would be: ''. Accessing the cached service requires an additional parameter, 'tiled=true' added to the cached service URL, so it would be: '', then click 'Next'.
    5. uDig Add Data 2
    6. You can then choose the layer / resource to be added to the map. Once chosen, click 'Finish'.
    7. uDig Add Data 3
    8. The above steps are only required once. Once the WMS has been added it should remain in your 'Catalog' tab in the bottom panel. Further layers can then be added to the map.
    9. uDig Final
    10. Additional documentation on how to use uDig can be found here.