What3Words Authentication: API Keys & Security (2026)

Authentication overview

What3Words utilizes API keys for authenticating requests to its Public API. This method ensures that only authorized applications can access the service, allowing What3Words to monitor usage, enforce rate limits, and provide analytics to developers. An API key acts as a unique identifier for a project or application, granting it permission to perform specific operations, such as converting a 3-word address to geographical coordinates or vice-versa.

The API key is typically passed as a query parameter in HTTP GET requests or within the request body for POST requests. All communications with the What3Words API, including the transmission of API keys, are secured using HTTPS. This encryption protocol helps protect data in transit from eavesdropping and tampering, which is a standard security practice for web APIs learn about Hypertext Transfer Protocol Secure.

Developers integrating the What3Words API should understand the implications of API key exposure and implement strategies to protect these credentials. The choice of authentication method, while simple, places the responsibility of key security largely on the client-side implementation.

Supported authentication methods

What3Words primarily supports API Key authentication for its Public API. This approach is common for APIs that do not require user-specific authorization but rather application-level identification and access control.

The following table outlines the details of the supported authentication method:

What3Words' API keys are public keys, meaning they are designed to be included in public-facing client-side code, but still require careful handling to prevent misuse. The What3Words API Reference details how to include the key in requests.

Getting your credentials

To obtain your What3Words API key, you need to register for a developer account on the What3Words developer portal. The process typically involves these steps:

1. Sign Up/Log In: Navigate to the What3Words developer documentation and either sign up for a new account or log in to an existing one.
2. Create a Project: Once logged in, you will usually be prompted to create a new project or application. This project acts as a container for your API keys and helps organize your usage.
3. Generate API Key: Within your project dashboard, there will be an option to generate a new API key. What3Words provides different key types for various environments (e.g., development, production) and usage tiers.
4. Restrict API Key (Optional but Recommended): Depending on the platform and your use case, you may be able to restrict your API key to specific domains (for web applications), IP addresses (for server-side applications), or Android/iOS app packages. This adds a layer of security by limiting where and by whom the key can be used. Consult the What3Words developer documentation for specific instructions on key restrictions.

It is crucial to store your API key securely and avoid hardcoding it directly into your source control. Environment variables, secret management services, or secure configuration files are recommended practices for storing API keys.

Authenticated request example

Authenticating with the What3Words API primarily involves including your API key in the request. The following examples demonstrate how to make an authenticated request using cURL, JavaScript, and Python to convert a 3-word address to coordinates.

cURL Example

This cURL command uses the convert-to-coordinates endpoint, passing the API key as a query parameter.

curl -X GET "https://api.what3words.com/v3/convert-to-coordinates?words=///filled.count.soap&key=YOUR_API_KEY"

JavaScript Example

For client-side JavaScript, you might use the fetch API. Remember to avoid directly exposing your key in production client-side code if it's a sensitive key, or use domain restrictions.

async function getCoordinates() {
  const apiKey = "YOUR_API_KEY"; // In a real app, load this securely (e.g., from an environment variable or a secure backend endpoint)
  const words = "///filled.count.soap";
  const url = `https://api.what3words.com/v3/convert-to-coordinates?words=${words}&key=${apiKey}`;

  try {
    const response = await fetch(url);
    if (!response.ok) {
      throw new Error(`HTTP error! status: ${response.status}`);
    }
    const data = await response.json();
    console.log(data);
  } catch (error) {
    console.error("Error fetching coordinates:", error);
  }
}

getCoordinates();

Python Example

Using the requests library in Python, you can construct an authenticated request:

import requests
import os

api_key = os.environ.get("WHAT3WORDS_API_KEY") # Recommended: load from environment variable
if not api_key:
    print("Error: WHAT3WORDS_API_KEY environment variable not set.")
    exit()

words = "///filled.count.soap"
url = f"https://api.what3words.com/v3/convert-to-coordinates"

params = {
    "words": words,
    "key": api_key
}

try:
    response = requests.get(url, params=params)
    response.raise_for_status() # Raise an exception for HTTP errors (4xx or 5xx)
    data = response.json()
    print(data)
except requests.exceptions.RequestException as e:
    print(f"Error fetching coordinates: {e}")

These examples demonstrate how to correctly include the API key for authentication. The key should always be passed securely, ideally not hardcoded directly into applications, especially for server-side implementations.

Security best practices

Securing your What3Words API key is critical to prevent unauthorized usage, potential billing issues, and service disruption. Adhering to these best practices will help maintain the integrity of your integration:

• Use HTTPS for All Requests: Always ensure that all communications with the What3Words API use HTTPS. This encrypts the API key and other data in transit, protecting them from interception. What3Words enforces HTTPS for all API endpoints, but it's important to confirm your client-side implementation also uses it consistently.
• Restrict API Keys: Wherever possible, apply restrictions to your API keys. What3Words allows you to restrict keys based on HTTP referrers (for web applications), IP addresses (for server-side applications), or application package names (for mobile apps). This prevents unauthorized applications from using your key even if it is exposed. Refer to the What3Words developer documentation for guidance on setting up key restrictions.
• Avoid Hardcoding Keys: Never hardcode your API keys directly into your source code, especially for server-side applications or public repositories. Instead, use environment variables, secret management services (e.g., AWS Secrets Manager, Google Secret Manager), or secure configuration files that are not part of version control. For client-side applications, if a key must be public, ensure it is heavily restricted.
• Rotate API Keys Regularly: Periodically generate new API keys and replace old ones. This practice minimizes the window of opportunity for an exposed key to be exploited. If you suspect a key has been compromised, revoke it immediately and generate a new one.
• Monitor API Usage: Regularly check your API usage statistics within the What3Words developer console. Unusual spikes in usage could indicate a compromised key or unauthorized activity. Set up alerts if the developer portal offers them.
• Segregate Keys by Environment: Use different API keys for development, staging, and production environments. This limits the blast radius if a key in a non-production environment is compromised.
• Server-Side Proxy for Client-Side Apps: For highly sensitive client-side applications, consider routing API requests through your own backend server. Your server can then add the API key before forwarding the request to What3Words. This completely shields the API key from the client application. This is a common pattern for securing API keys that are not designed for public client-side exposure learn about API key best practices from Google Cloud.