What3Words Getting Started: First API Call (2026)

Getting started overview

Integrating the What3Words API typically involves a sequence of steps: creating a developer account, obtaining API credentials, and then executing an initial API request to confirm connectivity and functionality. The What3Words API facilitates the conversion between 3-word addresses (e.g., ///filled.count.soap) and standard geographical coordinates (latitude and longitude), and vice-versa. This guide focuses on the essential steps required to make a first successful API call.

What3Words provides various SDKs for common programming languages, including JavaScript, Python, and Java, simplifying integration into different application environments. For initial testing and understanding, direct HTTP requests using tools like cURL are also effective. The API adheres to RESTful principles, using standard HTTP methods and JSON for request and response bodies, which is a common pattern in web service development, as described by W3C web architecture principles.

Quick reference

The following table summarizes the key steps for getting started with the What3Words API:

Create an account and get keys

Before making any API requests, you need a What3Words developer account and an associated API key. This key authenticates your requests and tracks your usage against your allocated quota, which includes a free tier of 10,000 requests per month.

Account creation process

1. Navigate to the What3Words Developer site.
2. Click on the "Sign Up" or "Get API Key" button.
3. Provide the required information, which typically includes your name, email address, and organization details.
4. Agree to the terms of service and complete any verification steps, such as email confirmation.

API key retrieval

Once your account is active, your API key will be available in your developer dashboard:

1. Log in to your What3Words developer account.
2. Locate the "API Keys" or "Credentials" section within the dashboard.
3. Your API key will be displayed. It is a long alphanumeric string. Treat this key as sensitive information; do not hardcode it directly into client-side code or public repositories. Best practices for API key management often involve using environment variables or secure configuration files, as recommended by Google Cloud's API key security guidelines.

Your first request

The most common initial request involves converting a 3-word address to coordinates. This demonstrates the core functionality and verifies your API key is correctly configured. We will use the convert-to-coordinates endpoint.

Using cURL for a direct HTTP request

cURL is a command-line tool for making HTTP requests, useful for quick testing without writing any code. Replace YOUR_API_KEY with your actual API key and ///filled.count.soap with a 3-word address of your choice.

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

A successful response will typically return a JSON object containing the coordinates, country, and other relevant details for the specified 3-word address:

{
  "country": "GB",
  "square": {
    "southwest": {
      "lng": -0.203923,
      "lat": 51.520847
    },
    "northeast": {
      "lng": -0.203881,
      "lat": 51.520888
    }
  },
  "nearestPlace": "Bayswater, London",
  "coordinates": {
    "lng": -0.203902,
    "lat": 51.520868
  },
  "words": "filled.count.soap",
  "language": "en",
  "map": "https://map.what3words.com/filled.count.soap"
}

Using the Python SDK

For more robust applications, using an official SDK is recommended. First, install the Python SDK:

pip install what3words

Then, you can make a request to convert a 3-word address to coordinates:

import what3words

# Replace with your API key
API_KEY = "YOUR_API_KEY"

# Initialize the client
api = what3words.Geocoder(API_KEY)

# Convert 3-word address to coordinates
res = api.convert_to_coordinates(words="filled.count.soap")

# Print the response
if res.get('coordinates'):
    print(f"Coordinates for filled.count.soap: {res['coordinates']['lat']}, {res['coordinates']['lng']}")
else:
    print(f"Error: {res.get('error')}")

This Python script will output the latitude and longitude, demonstrating a successful integration using the SDK.

Using the JavaScript SDK (Node.js)

For JavaScript environments, particularly Node.js for server-side operations, the SDK simplifies API interactions. Install the JavaScript SDK:

npm install @what3words/api

Then, make a request:

const what3words = require('@what3words/api');

// Replace with your API key
const API_KEY = "YOUR_API_KEY";

// Initialize the client
what3words.set=[API_KEY](https://what3words.com/business/pricing);

// Convert 3-word address to coordinates
what3words.api.convertToCoordinates({
  words: 'filled.count.soap'
})
  .then(response => {
    if (response.coordinates) {
      console.log(`Coordinates for filled.count.soap: ${response.coordinates.lat}, ${response.coordinates.lng}`);
    } else if (response.error) {
      console.error(`Error: ${response.error.message}`);
    }
  })
  .catch(error => console.error('API call failed:', error));

This Node.js example performs the same conversion, illustrating SDK usage in a JavaScript context.

Common next steps

After successfully making your first API call, you can explore additional functionalities and refine your integration:

• Reverse Geocoding: Use the convert-to-3wa endpoint to convert geographical coordinates back into a 3-word address. This is useful for displaying a 3-word address based on a user's current location or a selected point on a map.
• AutoSuggest: Implement the AutoSuggest API for real-time suggestions as users type, improving accuracy and user experience. This feature is particularly valuable in input forms where users enter 3-word addresses.
• Error Handling: Implement robust error handling in your application to manage various API responses, such as invalid API keys, rate limits, or malformed requests. The What3Words API Reference details possible error codes and messages.
• SDK Exploration: Familiarize yourself with the full capabilities of the SDKs, including their various methods and helper functions. SDKs often abstract away much of the HTTP request complexity, allowing developers to focus on application logic.
• Rate Limits and Quotas: Understand the API rate limits and your account's quota. Monitor your usage through the developer dashboard to avoid unexpected service interruptions, especially when scaling your application.
• Advanced Features: Explore features like Grid Section for retrieving specific grid square information, or the available options for language localization in the API responses.

Troubleshooting the first call

If your initial API call fails, consider the following common issues and solutions:

• Invalid API Key: Ensure your API key is correctly copied and pasted into your request. An incorrect key will typically result in an authentication error (e.g., HTTP 403 Forbidden). Double-check for extra spaces or incorrect characters.
• Rate Limit Exceeded: If you've made too many requests in a short period, you might hit a rate limit. Wait a few minutes and try again. The free tier has a limit of 10,000 requests per month, and exceeding this will also lead to errors. Check your usage in the developer dashboard.
• Incorrect Endpoint URL: Verify that the base URL and endpoint path are accurate. For example, the convert-to-coordinates endpoint should be https://api.what3words.com/v3/convert-to-coordinates.
• Missing Parameters: Ensure all required parameters, such as words for convert-to-coordinates or coordinates for convert-to-3wa, are included in your request. Missing parameters will result in a bad request error (HTTP 400).
• Network Connectivity: Confirm your development environment has an active internet connection and no firewall rules are blocking outgoing requests to api.what3words.com.
• SDK Configuration: If using an SDK, ensure it is correctly initialized with your API key. Review the specific SDK documentation for proper setup and method calls.
• JSON Parsing Errors: If you receive a successful HTTP status code but your application fails to process the response, check that you are correctly parsing the JSON output. Tools like JSON.parse() in JavaScript or Python's json module are standard for this.
• Outdated SDK Version: Occasionally, using an older SDK version might lead to compatibility issues with the latest API. Check the What3Words SDK documentation for updates.