search.jabber.network

Chat Room Search Engine

Overview

We offer two ways to access our data:

1. The XMPP API (preferred)
2. The anonymous HTTP API (discouraged)

If you have not noticed by now, the usage of the XMPP API is preferred. The reason is that you need to be authenticated to perform requests against the XMPP API, which makes it easier for us to work against abuse.

The HTTP API can be used anonymously, so we might rate-limit it more strictly in the future.

XMPP API

search.jabber.network offers a fully compliant Extended Channel Search (XEP-0433) API at api@search.jabber.network.

Please refer to the linked XEP document for instructions on how to interact with the API.

There is a description of the Legacy XMPP API (pre-XEP-0433) below, for historical purposes.

HTTP API

We offer a minimalistic HTTP-based JSON API to query the room list.

Rate limiting

We offer this service as a best-effort service. If you receive a 429 status code, please wait at least one minute for your next request.

Please avoid downloading the whole list unless you have to do so. If you want to do additional filtering locally, that is a good reason.

API calls

• Complete room listing (GET /api/1.0/rooms)
• Quick (unsafe) room listing (GET /api/1.0/rooms/unsafe)
• Search for rooms (GET /api/1.0/search)
• SVG "badges" for rooms (GET /api/1.0/badge)

{
	"items": [
		{
			"address": <(str) address of the room>,
			"nusers": <(int or null) approximate number of users>,
			"is_open": <(bool) whether it can be joined by anyone>,
			"name": <(str or null) name of the room>,
			"description": <(str or null) description of the room>,
			"language": <(str or null) primary language of the room>
		},
		< ... >
	]
}

{
	"page": <(int) page number>,
	"total": <(int) total number of items in all pages>,
	"pages": <(int) total number of pages>,
	"items": [
		{
			"address": <(str) address of the room>,
			"nusers": <(int or null) approximate number of users>,
			"is_open": <(bool) whether it can be joined by anyone>,
			"anonymity_mode": <(str) "semi" or "none", indicating the level of anonymity ("semi" = room moderators can see occupant JIDs, "none" = everyone can)>,
			"name": <(str or null) name of the room>,
			"description": <(str or null) description of the room>,
			"language": <(str or null) primary language of the room>
		},
		< ... >
	]
}

{
	"query": {
		<the expanded search request>
	},
	"result": {
		"last": <opaque pagination key (see above)>,
		"more": <(bool) flag which indicates that there may be more data available on a subsequent page>,
		"items": [
			{
				"address": <(str) address of the room>,
				"nusers": <(int or null) approximate number of users>,
				"is_open": <(bool) whether it can be joined by anyone>,
				"anonymity_mode": <(str or null) "semi" or "none", indicating the level of anonymity ("semi" = room moderators can see occupant JIDs, "none" = everyone can). May be null if the service currently lacks data.>,
				"name": <(str or null) name of the room>,
				"description": <(str or null) description of the room>,
				"language": <(str or null) primary language of the room>
			},
			< ... >
		]
	}
}

$ curl -s \
	--data '{"keywords": ["xsf"]}' \
	-H 'Content-Type: application/json; charset=utf-8' \
	https://search.jabber.network/api/1.0/search | jq -C .
{
  "query": {
	"after": null,
	"keywords": [
	  "xsf"
	],
	"min_users": 0,
	"sinaddr": true,
	"sindescr": true,
	"sinname": true
  },
  "result": {
	"items": [
	  {
		"address": "xsf@muc.xmpp.org",
		"anonymity_mode": "semi",
		"description": "Discussion room of the XMPP Standards Foundation",
		"is_open": true,
		"language": "en",
		"name": "XSF Discussion",
		"nusers": 66
	  },
	  {
		"address": "council@muc.xmpp.org",
		"anonymity_mode": "semi",
		"description": "Room where the XSF XMPP Council holds its meetings",
		"is_open": true,
		"language": "en",
		"name": "XMPP Council",
		"nusers": 23
	  },
	  {
		"address": "commteam@muc.xmpp.org",
		"anonymity_mode": "semi",
		"description": null,
		"is_open": true,
		"language": "en",
		"name": "XSF Communications Team",
		"nusers": 14
	  },
	  {
		"address": "editor@muc.xmpp.org",
		"anonymity_mode": "semi",
		"description": "Discussion room for the XSF Editor Team",
		"is_open": true,
		"language": "en",
		"name": "XSF Editor Team",
		"nusers": 12
	  }
	],
	"last": 12.1112915471192,
	"more": false
  }
}

<img src="https://search.jabber.network/api/1.0/badge?address=xsf@muc.xmpp.org"/>

Legacy XMPP API

The Legacy XMPP API is based on XEP-0004 (Data Forms) and XEP-0059 (Result Set Management) (don’t worry: the results are not in a XEP-0004 report!).

The search parameters are sent via a XEP-0004 form. The results are in a custom wire format which is paginated using XEP-0059 RSM.

The XMPP API endpoint is api@search.jabber.network.

Obtaining the search parameters form

To request the search form, send the following request:

<iq to="api@search.jabber.network" type="get">
	<search xmlns="https://xmlns.zombofant.net/muclumbus/search/1.0"/>
</iq>

Reminder: You have to set a unique id attribute on the IQ.

Note: You may find it weird that the to address is a bare JID. This is intended and correct. api@search.jabber.network is in fact a proxy service which delegates the query to one of possibly multiple workers.

The service will respond with the form (see below for the full form type specification):

<iq type='result' from='api@search.jabber.network'>
  <search xmlns='https://xmlns.zombofant.net/muclumbus/search/1.0'>
	<x xmlns='jabber:x:data' type='form'>
	  <field type='hidden' var='FORM_TYPE'>
		<value>https://xmlns.zombofant.net/muclumbus/search/1.0#params</value>
	  </field>
	  <field type='text-single' var='q' label='Search for'>
	  </field>
	  <field type='boolean' var='sinname' label='Search in name'>
		<value>true</value>
	  </field>
	  <field type='boolean' var='sindescription' label='Search in description'>
		<value>true</value>
	  </field>
	  <field type='boolean' var='sinaddr' label='Search in address'>
		<value>true</value>
	  </field>
	  <field type='text-single' var='min_users' label='Minimum number of users'>
		<value>1</value>
	  </field>
	  <field type='list-single' var='key' label='Sort results by'>
		<value>nusers</value>
		<option label='Number of online users'><value>nusers</value></option>
		<option label='Address'><value>address</value></option>
	  </field>
	</x>
  </search>
</iq>

Search parameters

q

Optional string. Operates like the search box on the website. If left blank, keyword search is disabled altogether and a full result is returned.

sinname

Optional boolean (default: true). Flag to indicate that the search should search within the MUC names.

sindescription

Optional boolean (default: true). Flag to indicate that the search should search within the MUC descriptions.

sinaddr

Optional boolean (default: true). Flag to indicate that the search should search within the MUC addresess.

min_users

Optional integer (default: 1). Minimum number of users in the MUCs to return.

key

The key of the result set management and the field by which the results are ordered. See below for details.

The key field specifies the order in which results are returned and also the field which is used for XEP-0059 pagination. Two values are allowed:

address

Order ascendingly by the address of the MUC. Paginating through this result will provide a duplicate-free but not necessarily complete view of the database (with respect to the keyword search and min users parameters). If a MUC is updated to match the search criteria or added while the pagination happens it may or may not be included in the complete result set.

nusers

Order descendingly by the number of users in the MUC. Paginating through the result may have duplicates and may not include all items.

Executing the search

To execute the search, the filled-out search form must be sent. For example, to search for xmpp.org in ascending order of the address with a page size of 5 and only returning MUCs which have at least one user, use:

<iq to="api@search.jabber.network" type="get">
  <search xmlns="https://xmlns.zombofant.net/muclumbus/search/1.0">
	<set xmlns="http://jabber.org/protocol/rsm">
	  <max>5</max>
	</set>
	<x xmlns="jabber:x:data" type="submit">
	  <field var="FORM_TYPE" type="hidden">
		<value>https://xmlns.zombofant.net/muclumbus/search/1.0#params</value>
	  </field>
	  <field var="q" type="text-single" label="Search for">
		<value>xmpp.org</value>
	  </field>
	  <field var="sinname" type="boolean" label="Search in name">
		<value>true</value>
	  </field>
	  <field var="sindescription" type="boolean" label="Search in description">
		<value>true</value>
	  </field>
	  <field var="sinaddr" type="boolean" label="Search in address">
		<value>true</value>
	  </field>
	  <field var="min_users" type="text-single" label="Minimum number of users">
		<value>1</value>
	  </field>
	  <field var="key" type="list-single" label="Sort results by">
		<value>address</value>
		<option label="Number of online users"><value>nusers</value></option>
		<option label="Address"><value>address</value></option>
	  </field>
	</x>
  </search>
</iq>

The XEP-0059 element is optional in the initial search request. It MAY be used to configure the page size. Note that the service may override your choice.

The server will then respond with the first page of the result set:

<iq type='result' from='api@search.jabber.network'>
  <result xmlns='https://xmlns.zombofant.net/muclumbus/search/1.0'>
	<item address='commteam@muc.xmpp.org'>
	  <name>commteam</name>
	  <nusers>10</nusers>
	  <is-open/>
	</item>
	[…]
	<item address='operators@muc.xmpp.org'>
	  <name>XMPP Service Operators</name>
	  <description>Discussion venue for operators of federated XMPP services</description>
	  <nusers>43</nusers>
	  <is-open/>
	</item>
	<set xmlns='http://jabber.org/protocol/rsm'>
	  <first>opaque-string-1</first>
	  <last>opaque-string-2</last>
	  <max>5</max>
	</set>
  </result>
</iq>

Note: The child element of the iq is a different one than used in the request!

The result contains of a sequence of items and a XEP-0059 element. The latter is used for pagination. The <max/> child is always included; it indicates the page size chosen by the service. If the number of items returned is less than the page size, you have reached the last page and should not continue to paginate further.

The result <item/> elements have the following syntax:

@address

This attribute carries the address of the result MUC.

<name/>

Optional string. The name of the MUC. May be omitted if unknown.

<description/>

Optional string. The description of the MUC. May be omitted if unknown.

<language/>

Optional string. The language of the MUC. May be omitted if unknown.

<is-open/>

Optional. Does not have children or text. Its presence indicates that the MUC is open to join by anyone.

<anonymity-mode/>

Optional string. Anonymity mode of the MUC. Either semi or none. semi indicates that only room moderators can see the occupants real JIDs. none indicates that everyone can see everyones JIDs.

<nusers>

Integer. Approximate number of users in the room.

Note: more fields may be added in the future without notice or changing the namespace.

Pagination

To paginate through the results, send the same form again and set the <after/> element of the XEP-0059 element to the value given in the <last/> element of the last page your received:

<iq to="api@search.jabber.network" id="xfdrffYzW2FTxdE2i6+0W" type="get">
	<search xmlns="https://xmlns.zombofant.net/muclumbus/search/1.0">
	<set xmlns="http://jabber.org/protocol/rsm">
	  <after>opaque-string-2</after>
	  <max>5</max>
	</set>
	<x xmlns="jabber:x:data" type="submit">
	  <!-- Your search goes here -->
	</x>
  </search>
</iq>

The server will then return the next page. You can repeat this until your recieve a result set which has fewer items than indicated in the <max/> element of the results RSM element.

Note: This service does not support the full XEP-0059 semantics. Paginating is only supported through the <after/> element.

Form specification

<form_type>
  <name>https://xmlns.zombofant.net/muclumbus/search/1.0</name>
  <doc>https://muclumbus.jabbercat.org/docs/api</doc>
  <desc>
	Form to search through a public MUC directory.
  </desc>
  <field
	 var='q'
	 type='text-single'
	 label='Search for'/>
  <field
	  var='sinname'
	  type='boolean'
	  label='Search in name'/>
  <field
	  var='sindescription'
	  type='boolean'
	  label='Search in description'/>
  <field
	  var='sinaddr'
	  type='boolean'
	  label='Search in address'/>
  <field
	  var='min_users'
	  type='text-single'
	  label='Minimum number of users'/>
  <field
	  var='key'
	  type='list-single'
	  label='Sort results by'/>
</form_type>