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 10 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.

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 staticmap, 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 web pages that have been downloaded from one of the web addresses you specify will be able to load Nearmap imagery. This is based on web browser support for the HTTP referer header field. A referrer address can contain subdirectories. For example, https://mywebsite.com/myapplications/app1
    • Access is allowed when one of the specified referer prefixes matches the beginning of the URL that is shown in the web browser.

    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 follows.


More About API Key Athentication in Nearmap


  • No labels