Page tree
Skip to end of metadata
Go to start of metadata

This guide includes the following sections:


Introduction

API Key authentication allows you to consume Nearmap imagery in an application without having to provide your Nearmap username and password as authentication credentials. Instead you include an API Key – a unique long string associated with a particular user on your Nearmap account – and then include that API Key in all requests to Nearmap endpoints, typically by appending it to a URL.

You manage API Keys using a simple user interface within your Nearmap profile; no API call is needed to create an API Key. An API Key is valid until you delete it; you do not have to regularly refresh it.

API Key authentication works for both desktop applications and custom web applications. If your application supports using map content via any of the supported Nearmap interfaces, including WMSTMS and Image API, you should be able to integrate Nearmap imagery with minimal configuration using an API Key.

You can configure an API Key so that it can only be used from a restricted set of IP addresses or applications. See Creating and managing an API Application below for details.

By design, you cannot use an API Key to log in to the Nearmap MapBrowser web application. Use your Nearmap username and password to log in to MAPBROWSER.

Organising Your Integrations

There are two key components to Nearmap API Key authentication:

  1. API Applications allow you to organise your Nearmap integrations, and to set different access restrictions for different integrations. You can have as many API Applications as you need on your Nearmap account. You must be a Nearmap administrator to create and manage API Applications. 

  2. Every user on a Nearmap account can create one API Key for each API Application on that account. Usage accrued by an integration that uses an API Key will be a recorded against the user who owns that API Key.

Creating and Managing an API Application

  1. Log in to Nearmap at https://admin.nearmap.com/welcome as a user who is a Nearmap administrator.

  2. Click the API Access tab at the top of the screen. If you do not see that tab, it is likely that you are not a Nearmap administrator.

  3. Click the Create New button.


  4. Enter an Application Name. This can be any string of characters. A good name would describe the integration that you intend to have with Nearmap imagery.

  5. You can optionally specify restrictions on which IP addresses or web sites can load Nearmap imagery via an API Key associated with this API Application:

    • IP restrictions: only IP addresses in the ranges you specify will be able to load Nearmap imagery. CIDR addresses are accepted. For example, 192.168.34.0/24.

    • Referrer restrictions: only URLs that begin with one of the specified referrer prefixes are allowed access to Nearmap imagery. This is based on web browser support for the HTTP referrer header field. 

      Enter here your referrer address/addresses, in a comma-separated list. A referrer address can contain sub-directories. For example, https://mywebsite.com/myapplications/app1.

      You must explicitly include https:// or http:// at the start of a Referrer Restrictions URL, the restriction will not work if this is missing. 

      Note: There is a character limit of 1 to 100 characters for the referrer restrictions.


    If the purpose of these restrictions is not clear to you, we recommend that you do not enter any restrictions.

  6. Click the Save button.

Your API Application should be displayed on the screen. Each user on your Nearmap account can now create an API Key for that API Application.

As a Nearmap administrator, you can also use the API Access tab to:

  • Manage your existing API applications
  • View which users have created an API Key for an API application
  • Create and manage your own API Keys (using the same interface as non-admin users)

Creating an API Key

Once an administrator has created an API Application, you can log in to Nearmap to create an API Key for that application.

  1. Log in to Nearmap at https://admin.nearmap.com/welcome.

  2. If you are a normal user, click the My API Keys button. If on the other hand you are an administrator, select API Access from the top menu, and click the My API Keys link.

  3. Choose an application from the drop-down list.

    If there is no application in the drop-down list, or the API Application you want is not there, contact your organisation's Nearmap administrator.

  4. Click Create API Key.

The API Key is now created – it is the long string of characters in the API Key column. You can use it in your integrations, as explained in Using an API Key in Nearmap Integrations.

Deleting an API Key

If you no longer need an existing API Key, you can log in to Nearmap to delete it.

  1. Log in to Nearmap at https://admin.nearmap.com/welcome.

  2. If you are a normal user, click the My API Keys button. If on the other hand you are an administrator, select API Access from the top menu, and click the My API Keys link.

  3. Find your API Key and click the Delete icon.

More About API Key Authentication in Nearmap


  • No labels