Developer

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 voiceapi@what3words.com 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
Copied

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

$ python3 --version Python 3.7.4
Copied

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 dependencies are required to run the sample application. Because of this, we recommend the creation of a virtual environment to avoid adding to your global dependencies. If you're happy to install directly into your global dependencies, you can skip the creation of a virtual environment.

# Install virtualenv
pip install virtualenv

# Create the virtual environment
virtualenv -p python3 venv

# Activate the virtual environment
source venv/bin/activate
Copied

Install dependencies

Install the following dependencies 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
Copied

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 exampleclient.py.

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, \
    connectWS

import websocket
import json
import pyaudio
import wave
import threading

W3W_API_KEY = 'YOUR_API_KEY'
VOICE_LANGUAGE = 'en'

class VoiceApiProtocol(WebSocketClientProtocol):
    def __init__(self):
        super().__init__()
        self.audio = 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
            }
        }
        self.sendMessage(json.dumps(start_recognition).encode('utf8'))

    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 speech recognition
            print("Say any 3 word address...")

            # Run the audio stream asynchronously
            self.audio_stream = self.audio.open(
                format=self.pyaudio_format,
                channels=1,
                rate=self.sample_rate,
                input=True,
                frames_per_buffer=self.frames_per_buffer,
                stream_callback=self.send_audio)
        elif message_type == "Suggestions": # Suggestions have been returned
            # Close the audio stream
            self.audio_stream.stop_stream()
            self.audio_stream.close()

            # Print the results
            print("\nSuggestions:")
            print("============\n")
            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))

        reactor.stop()

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


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

    connectWS(factory, ssl.ClientContextFactory())
    reactor.run()
Copied

Step 5

Running

From the command line start the application as follows

python client.py
Copied

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 client.py
Say any 3 word address...

Suggestions:
============

{
    "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"
        }
    ]
}
Copied