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

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 28 Next »

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.

In addition to this guide, you can view our Service Portal tutorial video on How to Generate API Keys.

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.

API Key Status and Refresh

You can view the status of your API keys and check the key dates relating to each API key.

  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.

The API keys table shows the status of the API key. The possible status options are:

  • Active - the API key is active and can be used.
  • Inactive - the API application to which the API key is linked has been made inactive. An account administrator will need to reactivate the application for this key to be used.
  • Stale - the API key may not work with the new APIs, refresh the API key to update it.
  • Expiring - the API key will expire in the next 30 days, refresh the API key to prevent any loss of access.
  • Expired - the API key has expired, refresh the API key to restore access.

To refresh the API key and to view more information about it, click the name of the API application from the table. In addition to the status of the API key, you can see the date the API key was created, when it was last used, and when it expires.

Use the Refresh button to refresh the API key:

More About API Key Authentication in Nearmap


  • No labels