WebSocket Gateway

The API provides a real-time WebSocket Gateway that streams events as they happen on the platform. You can listen to votes, favourites, and other activities live.

Connection Details

• Production URL: wss://api.thedogapi.com
• Staging URL: wss://staging-api.thedogapi.com
• Transport: websocket (Long-polling is disabled)

Authentication

You must pass your API Key to connect. This can be done via the x-api-key header or query parameter, depending on your client library.

[!IMPORTANT] A valid API key is required to establish a connection.

Example Code

We have a dedicated repository with full code examples showing how to connect, authenticate, and render live events on a map.

View WebSocket Examples on GitHub

Basic Connection (Socket.io)

/*
  This example uses Socket.io Client v4
  <script src="https://cdn.socket.io/4.7.2/socket.io.min.js"></script>
*/

const socket = io('https://api.thedogapi.com', {
    transports: ['websocket'], // Force websocket transport
    auth: {
        'x-api-key': 'YOUR_API_KEY'
    }
});

socket.on('connect', () => {
    console.log('Connected!');
});

socket.on('disconnect', () => {
    console.log('Disconnected');
});

// Listen for all events
socket.onAny((eventName, data) => {
    console.log(`Received ${eventName}:`, data);
});

Events

The gateway streams various events. The payload structure generally follows this pattern:

{
  "id": 12345,
  "image_id": "b1",
  "value": 1,
  "created_at": "2023-11-20T10:00:00.000Z",
  "_metadata": {
    "event_type": "vote",
    "country_code": "US"
  }
}

If you send attach_image: true in your auth payload, the server will attempt to look up and attach image details to the event, though this may add latency.