Skip to main content
Skip table of contents

Push streaming code examples

Listening to a websocket stream can be very simple, but unlike Weather API it is not as easy as typing a formatted URL into a browser. Here we have collected some very bare code examples you can use to get started with listening to WebSockets in your applications.


Javascript (and NodeJS) is a popular, native language for working with WebSockets in a browser or server environment. The WebSocket object/class is a native part of the language, and creates a very simple interface for receiving WebSocket Messages. Learn More

var my_token = "Your API Token";
var stream_server = "wss://";
var query_arguments = "units=english&stid=KIAD,KDCA&vars=air_temp,relative_humidity";

// first you should define a function that is called every time a message is received
function message_received(message_event) {
	// this function will be called every time there is a new message. And 
	// the message will be given to the function as a special object.
	// First you should extract the JSON object from the message
	var message_json = JSON.parse(;

	// and now you can process your streamed data. Use the `type` key to 
	// determine what kind of message it is
	if (message_json.type == "auth") {
		// auth messages contain your session ID, which you can use to 
		// reconnect where you left off if you have network trouble

	} else if (message_json.type == "data") {
		// this message contains a list of observations
		var ob_index;
		for (ob_index in {
			//... handle your new observations
	} else if (message_json.type == "metadata") {
		// this is metadata!


// we had to define that function first, but now we can connect to the socket
// and set that function to be what is called when a message is received. 

// and create the socket - this connects and starts listening almost immediately.
var socket = new WebSocket(stream_server+my_token+"/?"+query_arguments);
socket.onmessage = new_message;


This is a terminal utility built on NodeJS, that you can use to direclty watch a websocket from a command line. When specifying a URL with parameters in the command line, remember to enclose the URL in quotes. Learn about wscat.

wscat -c "wss://{Your Token}/?{Arguments}"


There are a number of Python implementations of websockets, and they all work largely the same. This quick example uses websocket-client (pip install websocket-client), but others, including Tornado have the feature built-in.

from websocket import create_connection
import json

my_token = "Your API Token"
stream_server = "wss://"
query_arguments = "units=english&stid=KIAD,KDCA&vars=air_temp,relative_humidity"

# then you simply create your connection
ws = create_connection(stream_server+my_token+"/?"+query_arguments)

# and then you need to read for new messages from the connection. Do this
# using an infinite while loop.

while True:
	data = ws.recv()
	json_data = json.loads(data);

	# and now do things with your received data, before going back to 
	# the socket for another message.

You can learn more about websocket-client here. Learn about tornado.websocket here.

JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.