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

Create_API_Application.png






















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.

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

API_Keys.png

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.

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

Using an API Key in a Nearmap Integration

Use your API Key to authenticate with all Nearmap's HTTP-based services: WMSWMTSTMS and staticmap.

The API Key must be sent with every request to the service. 

The API key can be sent with the request using the apikey URL parameter or an HTTP Authorization header.

Using API Key in a URL

Include the apikey=YOUR_API_KEY name/value pair in the URL (replacing "YOUR_API_KEY" with the sequence of characters that make up your API Key).

Here are example URL formats using API Key for our WMS and TMS services, both for Australia and the US:

WMS

TMS

See our Developer Documentation for further examples for each of our APIs.

See our GIS and CAD Integration pages for specific instructions for various third-party GIS applications.

WMS Links

The Manage API Keys page of your Nearmap profile contains handy links to our WMS services containing your API Key. Click on the WMS links icon. The following screen will pop up:

WMS_Links.png

Click on the Australia or United States button to copy the WMS link, including your API Key, to the clipboard. Paste it into your GIS application when prompted.

Using API Key in an HTTP Authorization Header

The API Key can be presented in an HTTP Authorization header. The format of the header is as follows:


Authorization: Apikey YOUR_API_KEY


The case of the authorization type is significant: the string must be "Apikey" with a capital A and all other characters lowercase.

Here are example cURL commands for our TMS API:

Troubleshooting

Error Codes and Descriptions

An unsuccessful request to a Nearmap service will return an HTTP status code indicating an error. The status code for authentication failure is 401 Unauthorized. All API Key related failures will return a 401 status code.

In addition to the status code of 401, a small JSON payload is returned describing the error. The possible JSON error descriptions are:

{"error":"Failed to validate IP or referer"} — the failure is related to the IP range or HTTP referer restrictions that were set on the API Application associated with the API Key. Check whether the request came from a valid IP address and referer. A useful diagnostic step is to remove the restrictions from the API Application, or use a different API Application that does not have the restrictions (and different API Key for that API Application), and see if the error still occurs.

{"error":"API key not found"} — all other API Key related errors will return this message.

The means of finding out the HTTP status code and the JSON payload will depend on the application that you are trying to integrate with Nearmap. 

Capitalization

If you are using an HTTP Authorization header, the Authorization type must be "Apikey" – note the capital A.

(If on the other hand you are using the "apikey" parameter in the URL, capitalization is not significant. For example, all of the following are valid in a URL: "apikey=", "APIKEY=", "ApIkEy=".)

Is Everything Enabled?

Check that the API Application associated with the API Key is enabled.

Check that the user who owns the API Key is enabled and licensed. See Managing your Nearmap licenses and user logins for details.

Timeout Period

 Changes related to an existing API Key can take up to an hour to take effect. For example:

  • If you disable an API Application, the API Key may continue to provide access for up to an hour.
  • Changes to the access restrictions on an API Application may take up to an hour to take effect.

Further Information

Advantages of API Key Authentication

API Key authentication has the following advantages over providing username and password when integrating with Nearmap imagery:

  • More secure: some existing applications do not provide a means of passing through username and password in a secure manner. API Key authentication is a more secure approach than using HTTP Basic Authentication or appending username and password directly to a URL.
  • More integrations possible: some existing applications do not provide a means of passing through username and password at all, and as such have not been able to consume Nearmap imagery. Many of those applications will work with API Key.
  • Simpler: for customer applications, API Key authentication is a simpler approach than programmatically generating an access ticket that has to be periodically refreshed or programmatically revoked. Using an API Key may eliminate the need for any server-side programming for simple web applications.

Common Usage Scenarios

API Applications and API Keys together provide a flexible means of organising your Nearmap integrations. Here are some common usage scenarios:

  • Existing GIS application (e.g. Esri ArcGIS for Desktop): you could have one API Application for all your GIS applications, or alternatively one for each application, if they had different access restrictions. Each user of the GIS application may use their their own distinct API Key.
  • Custom web application: you could have just a single API Application, or alternatively you could have separate API Applications for your different hosting environments – for example, development, staging, production. All usage of Nearmap imagery is via one single API Key. Commonly you would create a separate Nearmap user that only consumed imagery via that API Key.

Support for Legacy Authentication Methods

API Key authentication is Nearmap's supported integration authentication mechanism.

We no longer provide support for new integrations using legacy authentication mechanisms:

  • Ticket-based authentication
  • HTTP Basic authentication
  • Username and password in a URL

Those legacy authentication methods are still in place; existing integrations using those methods are unaffected. 

At some point we will remove the ability to authenticate via those mechanisms. We will be in touch with customers before carrying out any changes to the available authentication methods.

  • No labels