Documentation

HomeDashboard

Filtering & Subscriptions

By default, every connected socket receives all alerts for all cities. The filtering system lets you subscribe only to the alert types and cities you care about - reducing bandwidth, simplifying your handler logic, and ensuring your application only processes relevant data.

Connection-Time Filtering

Via auth ObjectRecommended

Pass types and/or cities arrays directly in the auth payload.

javascript
1import { io } from 'socket.io-client';
2

3const socket = io('https://sirenapi.orielhaim.com', {
4  auth: {
5    apiKey: 'your-api-key-here',
6    // Only receive missile and earthquake alerts
7    types: ['missiles', 'earthQuake'],
8    // Only for these cities
9    cities: ['תל אביב - מרכז העיר', 'חיפה - כרמל ועיר תחתית']
10  }
11});
12

13socket.on('alert', (alerts) => {
14  // alerts will only contain missiles/earthquakes
15  // and only for תל אביב and חיפה
16  console.log(alerts);
17});

Via Query Parameters

Useful for environments where the auth object is not available or for simple testing. Values are comma-separated.

javascript
1const socket = io('https://sirenapi.orielhaim.com/?types=missiles,earthQuake&cities=תל אביב,חיפה', {
2  auth: {
3    apiKey: 'your-api-key-here'
4  }
5});

Via Custom Headers

Useful for non-browser clients or when you need to set subscriptions at the transport level.

javascript
1const socket = io('https://sirenapi.orielhaim.com', {
2  auth: { apiKey: 'your-api-key-here' },
3  extraHeaders: {
4    'x-alert-types': 'missiles,earthQuake',
5    'x-alert-cities': 'תל אביב - מרכז העיר,חיפה - כרמל ועיר תחתית'
6  }
7});

Runtime Subscription Updates

You can change your subscription at any time without disconnecting. Emit a subscribe event with your new preferences. The server will confirm with a subscribed event.

javascript
1// Initial connection - receive everything
2const socket = io('https://sirenapi.orielhaim.com', {
3  auth: { apiKey: 'your-api-key-here' }
4});
5

6// Later: narrow down to missiles only in Tel Aviv
7socket.emit('subscribe', {
8  types: ['missiles'],
9  cities: ['תל אביב - מרכז העיר']
10});
11

12// Server confirms the new subscription
13socket.on('subscribed', (sub) => {
14  console.log('Now subscribed to:', sub);
15  // { types: ['missiles'], cities: ['תל אביב - מרכז העיר'] }
16});
17

18// Even later: go back to receiving everything
19socket.emit('subscribe', {
20  types: '*',
21  cities: '*'
22});
23

24// You can also update just one dimension
25socket.emit('subscribe', {
26  types: ['missiles', 'earthQuake'],  // filter types
27  cities: '*'                          // but all cities
28});

Error Handling

If the subscription payload is invalid, the server emits an error event.

javascript
1socket.on('error', (err) => {
2  console.error('Subscription error:', err.message);
3  // { message: 'Invalid subscription params' }
4});

Parameter Reference

ParameterTypeDefaultDescription
typesstring[] | string | "*""*" (all)Alert types to subscribe to. Pass an array of type strings, a comma-separated string, or "*" for all.
citiesstring[] | string | "*""*" (all)City names to filter by. Must match the exact city name from the Cities Catalog. Pass an array, a comma-separated string, or "*" for all.

Where to Pass Parameters

MethodTypes ParamCities ParamPriority
auth objectauth.typesauth.citiesHighest
Query string?types=...?cities=...Medium
Headersx-alert-typesx-alert-citiesLowest