Introduction

Nearmap WMS integration allows users of off-the-shelf GIS and CAD applications to load high-resolution imagery on demand.

To consume Nearmap imagery via WMS, you must authenticate using API Key Authentication, and obtain either a Simple WMS URL or a Custom WMS URL to load in the application.

Once authenticated, your software package will have a way for you to specify:

• The Nearmap layer you want to view
• The coordinate reference system you want to use to view the layer

Nearmap will provide the best projection for the WMS imagery.

This guide includes the following sections:

WMS 2.0 Services

There are two available services for WMS 2.0:

• Simple WMS - provides a WMS URL that has latest imagery only
• Custom WMS - allows a user to define a custom area/s and get a personalised WMS URL with this/these area/s only

Video: Introducing the Nearmap WMS 2.0

Accessing the WMS 2.0 Services

In order to obtain either a Simple WMS URL or a Custom WMS URL, you will need to access the Services in the customer portal.

You can either use this direct link: https://admin.nearmap.com/account/user-management/#/integration/services or follow these steps:

1. Log in to Nearmap at http://admin.nearmap.com/welcome.
   
2. Select My Profile.
   
3. Go to the API Access tab, and select the Services tab:
   
   
   
4. Make sure you have an API Application, as well as an API Key.

Simple WMS

The Simple WMS provides a URL that has the latest imagery for each region. The layer is shown only if you have access to that region (e.g. US, Australia, New Zealand). 

Obtaining a Simple WMS URL

1. Access the WMS 2.0 services - https://admin.nearmap.com/account/user-management/#/integration/services.
2. In the Simple Service, choose an application from the drop-down list.
3. Copy the URL:
   

You can now use the URL in GIS applications to load Nearmap imagery using the Nearmap Web Map Service (WMS). We have examples of how to use the WMS 2.0 integration in both ArcGIS Pro and QGIS.

Simple WMS URL Structure

The Simple WMS URL looks like this: 

https://api.nearmap.com/wms/v1/latest/apikey/<APIKEY>

Simple WMS Layers

The Simple WMS displays the following layers:

• Nearmap WMS - the combination of all the latest imagery of all the regions to which the user has access, overlaid on a satellite basemap
• Nearmap - the combination of all the latest imagery of all the regions to which the user has access
• Country Latest - the latest imagery for that country, without the satellite background
• Satellite - just the satellite imagery (NASA Blue Marble circa 2004)

Custom WMS

The Custom WMS provides a URL that has the imagery for the areas you define.

Obtaining a Custom WMS URL

1. Access the WMS 2.0 services - https://admin.nearmap.com/account/user-management/#/integration/services.
2. Either choose an existing custom service and jump to step 7 or create a new one. To create a custom service click the + above Add Custom Service:
   
3. Name the service (choose a meaningful name), then click Add Area:
   
   
   
4. Use the search box to search for your location, then draw the area you wish to add:
   
5. Name the area (choose a meaningful name), then choose whether to add start and end dates. If you do specify the dates, you will limit the response to the dates within this range. Click Continue:
   
   
6. You can add more areas to the WMS service if you want to. When you are finished close the window.
7. In the service you just created, choose an application from the drop-down list.
8. Copy the URL:
   

You can now use the URL in GIS applications to load Nearmap imagery using the Nearmap Web Map Service (WMS). We have examples of how to use the WMS 2.0 integration in both ArcGIS Pro and QGIS.

Custom WMS URL Structure 

The Custom WMS URL that we provide you looks like this:

 https://api.nearmap.com/wms/v1/places/<PLACES_ID>/apikey/<APIKEY>

Custom WMS Layers

Once added to the WMS Client, the resulting catalog looks like this:

In the above picture, you can see user defined names:

• FY20 Projects  - The name of the service
• Bondi beach, NSW - User defined area name
• 2019-01-27 Sydney - A layer corresponding to a survey from that date that was automatically created by the WMS server 
• Newtown, NSW combined - A layer that was automatically created by the WMS server. Contains all the imagery from the area within the optionally specified dates, with latest on top

Datum Changes

We support the most popular local datums for all of our imagery. Depending on which coordinate system your GIS application is configured with, you can request imagery in the following coordinate systems:

• Australia - GDA94 and GDA2020
• USA - NAD83
• Canada - NAD83CSRS
• New Zealand - NZGD2000 

When requesting imagery using WGS84 coordinate systems, namely EPSG:4326 (WGS 84) and EPSG:3857 (Web Mercator, Spherical Mercator, Pseudo-Mercator), our WMS service will automatically return imagery that has been converted to a local datum as per the table below.

For Australian Customers – assumed datum

Several web applications assume GDA94 where the datum is not specified. (You can see from the table above that in Australia, Nearmap WMS 2.0 defaults to GDA2020.)

We provide a way to force the returned imagery to GDA94 with a custom request parameter DATUM. The behaviour of this parameter depends on the projection the imagery is requested in (SRS Parameter), as shown in the table below.

What is the advantage of this?

If your application relies on assumed GDA94, the alignment and accuracy can be improved by a significant margin, as you can see in the images below.

Default behaviour

With GDA94 override

Suggestions on Image Format

Nearmap supports PNG and JPEG through the WMS service. Most WMS applications will request maps from a WMS server using PNG by default. When loading raster maps, such as Nearmap imagery, PNG has several advantages and several disadvantages. Please see below the recommendations for configuring your application.

When to Use PNG

PNG has a transparency channel, which means you can overlay Nearmap imagery on top of another basemap (for example a worldwide satellite layer or a roadmap). This works best when at small scale, for example when using a city or statewide extent. Note that PNG imagery is not compressed as much as JPEG and it will take longer to download. 

When to Use JPEG

Use JPEG for working with imagery at large scale. At house or suburb level, the chances of being on the Nearmap boundary are much smaller, which means that you won't need the transparency capability of PNG. Note that if you do come across a boundary, the areas with no data are rendered as black.

WMS 2.0 FAQs

Should I use Simple or Custom WMS?

The simple WMS should be used if you want the only latest imagery for your area (Australia/New Zealand/USA/Canada). You will not be able to perform geofencing or navigate time. Custom WMS will allow you to perform geofencing and to set up specified regions as the only imagery you can view. For those regions, you will be able to navigate the time and set boundaries for the dates.

Where can I find the options for Simple or Custom WMS?

You can find the options here: https://admin.nearmap.com/account/user-management/#/integration/services. You can then choose from Simple or Custom WMS. 

Is WMS 2.0 more accurate than what I am currently using?

Australia - We have adjusted the datum of the imagery that is returned by default when you don’t specify a projection, i.e. rely on application defaults. WMS 2.0 will automatically adjust the imagery to GDA2020 coordinate system for Australia and NZGD2000 for New Zealand. This will reduce positional errors and projection mismatches ensuring your imagery lines up. WMS 2.0 will continue to support the GDA94 MGA zone projections in Australia.

United States - We have adjusted the datum of the imagery that is returned by default when you don’t specify a projection, i.e. rely on application defaults. WMS 2.0 will automatically adjust the imagery to NAD83 coordinate system. This will reduce positional errors and projection mismatches ensuring your imagery lines up. WMS 2.0 will now support all local state/plane projections in the United States (EPSG codes).

What are the best practices for defining areas?

Use simple boundaries around your areas of interest. The imagery is not requested until you interact with the application, so there is little difference in what imagery is returned when the custom service is used.

Are there limits to the Custom WMS services?

• Maximum number of WMS places - 50
• Maximum number of areas per place - 10
• Maximum area size - 5,000 km²
• Maximum width or a height of an area - 500 km
• Maximum number of characters for place name - 100
• Maximum number of characters for an area name - 100
• Maximum number of nodes in an area geometry - 1000
• Allowed characters in place/area name - No character restrictions

Do bigger areas in custom WMS contribute more to my usage?

No. The areas that you define for your custom service are simply instructions on how to build a list of layers in that service. At the time of creation, no requests for imagery within the area of interest are made. Usage is accrued only when you bring the WMS service into your GIS application and add it to the map.

Does interacting with the imagery in the area definition window count towards my usage?

Yes. When you define an area a small amount imagery is loaded to provide context for where we have coverage. We envisage that there will be very little usage coming from this tool because:

• The map is very small, i.e. not full screen
• It is used infrequently to create services
• It is typically used at small scale with minimal interaction

How do I use GDA2020 projections?

Available in Simple and Custom WMS. For Simple WMS all AU MGA zones are available in both GDA94 and GDA2020. For Custom WMS only the zones that intersect with the area of interest will be available as an option to request imagery in.

How do I use State Plane projections?

Only available in Custom WMS. Only the state plane projections that intersect with the area of interest will be available as an option to request imagery in.

Can I upload a KML/Shapefile/FileGeoDatabase to define my areas to limit usage to precisely my areas?

No, you need to draw your areas, and the usage is only incurred at the time of browsing imagery in your GIS application.

When selecting an area can I select our local government boundary?

Yes, you can select any area, and it doesn't have to be exact. You will need to draw the area though, you cannot import your boundaries.

When you create an area in the self-service API portal, you're defining a template/metadata for that particular service, at that point no data is downloaded. We recommend that when you are interested in an area you roughly sketch out around that area, it doesn't matter if it is not following your local government area boundaries. The data is only downloaded when you bring it into the application, and you start interacting with the imagery in the application. 

Is there a way to know what is the date of the latest imagery?

Yes, in custom WMS you can know the date of the latest imagery, while in simple WMS you cannot. When you bring in the in the custom WMS the date layers are synced up to the latest imagery, and you know exactly which dates you are bringing in. With simple WMS there is no way to get at the dates, since it is a very simple lightweight service.

Does accessing the data from the WMS contribute to our overall usage allowance? 

Yes. This has always been the case, and the data from the WMS will continue being counted.

When loading into QGIS without the satellite imagery, why wasn't I able to remove the black around the aerial imagery?

The reason for that is that is probably because bringing your layer through QGIS brings it in by default with JPEG. JPEG does not have transparency support, so when there are areas with no data, they are displayed as black. We recommend that if you want to look at a zoomed out version of Nearmap imagery, for example when you're looking at a whole city or state, bring it in as PNG. If you're working mainly with zoomed in imagery, bring it in as JPEG. 

You can change the image format in QGIS to PNG by going to the Layer Properties → Display, and selecting the image format you want.

If we create many areas, does it have a performance impact?

The performance impact is not so much dependent on the size of the area, but on the number of surveys you bring back. There is a limit on how big an individual area can be, currently set at about 5000 km², and you can specify up to ten areas in the same service. If you bring in ten metropolitan areas around Australia, you could be loading thousands of surveys. That would slow down your initial loading into your GIS application.

Can I specify a polygon programmatically?

No, you cannot create a polygon programmatically. 

Can we limit the date range when creating the custom polygon?

Yes, the custom WMS allows you to limit the date range. You can specify either start date or end date, or both. It limits the surveys you get back as layers in your service. 

When you constrain a start date, to exclude older imagery, for an area if no more recent imagery is available, is a blank layer returned or your default, low-res (old) satellite imagery?  It would be very useful to see that there is no recent imagery after the constrained end date.

You simply get no layers if you create an area with a polygon and restrict the dates to a particular range. The satellite layer, which was by default included in our last version of WMS, is no longer included in the responses, so you do not get satellite imagery unless you explicitly ask for it. So yes, it would be possible to see that there is no recent imagery after the constrained end date.