Developer | what3words
We use cookies, including third party cookies, to improve your experience and for marketing purposes. By continuing to browse we assume you have consented to their use.Learn more
got it

Python Quick Start

This sample Python application uses the microphone to stream realtime audio into our Voice API. Once the dependencies have installed, users should be able to execute the code sample provided, speak a what3words 3 word address, and have a list of suggestions displayed back to the console.

Step 1

  1. Get your free API key.
  2. Currently the Voice API is in beta, and therefore, access is granted upon request. Please contact us at to enable the Voice API for your account.

Step 2

Python Version

This sample application has been developed for Python 3, and is not compatible with Python 2.

You can check your Python version from the command line with the following command:

$ python --version
Python 3.7.4

If you have Python 2 installed, you can try the same command with python3

$ python3 --version
Python 3.7.4

If you do not have Python3 installed, you will need to install it on your system before being able to run this example code.

Step 3

Virtual Environment

A number of Python dependancies are required to run the sample application. Because of this, we recomend the creation of a virtual environment to avoid adding to your global dependencies. If you're happy to install directly into your global dependancies, you can skip the creation of a virtual environment.

# Create the virtual environment
virtualenv -p python3 venv

# Activate the virtual environment
source venv/bin/activate

Install dependancies

Install the following dependancies using the pip commands provided

pip install twisted
pip install pyOpenSSL
pip install autobahn twisted
pip install websocket
pip install pyaudio
pip install service-identity

Step 4

Configuring the sample application

You will need to create a new Python file using a plain text editor of your choice, this file could be called anything, for

Copy and paste the Python code from the listing below into the newly created file.

The only configuration required is to set the two variablesW3W_API_KEY and VOICE_LANGUAGE. ReplaceW3W_API_KEY with your Voice API enabled API key, andVOICE_LANGUAGE with the desired voice language code.

from twisted.internet import reactor, ssl

from autobahn.twisted.websocket import WebSocketClientFactory, \
    WebSocketClientProtocol, \

import websocket
import json
import pyaudio
import wave
import threading


class VoiceApiProtocol(WebSocketClientProtocol):
    def __init__(self):
        super().__init__() = pyaudio.PyAudio()
        self.sample_rate = 16000
        self.pyaudio_format = pyaudio.paInt16
        self.raw_encoding = "pcm_s16le"
        self.frames_per_buffer = 4096

    def onOpen(self):
        # Initiate the recognition
        start_recognition = {
            "message": "StartRecognition",
            "audio_format": {
                "type": "raw",
                "encoding": self.raw_encoding,
                "sample_rate": self.sample_rate

    def onMessage(self, payload, isBinary): # Message recieved from the Server
        message = json.loads(payload.decode('utf8'))

        message_type = message["message"]
        if message_type == "RecognitionStarted": # Begin voice recognition
            print("Say any 3 word address...")

            # Run the audio stream asynchronously
            self.audio_stream =
        elif message_type == "Suggestions": # Suggestions have been returned
            # Close the audio stream

            # Print the results 
            print(json.dumps(message, indent=4))
    def onClose(self, wasClean, code, reason): # Connection with the server closed
        if code != 1000:
            print("Connection closed with Error")
            print("Code: {}".format(code))
            print("Reason: {}".format(reason))


    def send_audio(self, in_data, frame_count, time_info, status_flags):
        """Continuously collect data from the audio stream, into the WebSocket."""
        return None, pyaudio.paContinue

if __name__ == '__main__':
    # create a WS client factory with our protocol
    factory = WebSocketClientFactory(
        "wss://{}&voice-language={}".format(W3W_API_KEY, VOICE_LANGUAGE))
    factory.protocol = VoiceApiProtocol

    connectWS(factory, ssl.ClientContextFactory())

Step 5


From the command line start the application as follows


You should then be prompted to Say any 3 word address.... Speak any 3 word address into the microphone, and wait for the suggestions to print back to the console. You should expect output such as the following

$ python 
Say any 3 word address...


    "message": "Suggestions",
    "suggestions": [
            "country": "GB",
            "nearestPlace": "Bayswater, London",
            "words": "filled.count.soap",
            "distanceToFocusKm": 0,
            "rank": 1,
            "language": "en"
            "country": "GR",
            "nearestPlace": "Týrnavos, Thessaly",
            "words": "filled.count.soaped",
            "distanceToFocusKm": 0,
            "rank": 2,
            "language": "en"
            "country": "CA",
            "nearestPlace": "Saskatoon, Saskatchewan",
            "words": "filled.count.sobered",
            "distanceToFocusKm": 0,
            "rank": 3,
            "language": "en"
Back to top