Querying the Source Master Server

When a Source server starts it can optionally add it self to an index of live servers to enable players to find the server via matchmaking and the in-game server browsers. It does this by registering it self with the “master server”. The master server is hosted by Valve but the protocol used to communicate with it is reasonably well documented.

Clients can request a list of server addresses from the master server for a particular region. Optionally, they can also specify a filtration criteria to restrict what servers are returned. valve.source.master_server provides an interface for interacting with the master server.

Note

Although “master server” is used in a singular context there are in fact multiple servers. By default valve.source.master_server.MasterServerQuerier will lookup hl2master.steampowered.com which, at the time of writing, has three A entries.

valve.source.master_server

class valve.source.master_server.MasterServerQuerier(address=('hl2master.steampowered.com', 27011), timeout=10.0)

Implements the Source master server query protocol

https://developer.valvesoftware.com/wiki/Master_Server_Query_Protocol

__iter__()

An unfitlered iterator of all Source servers

This will issue a request for an unfiltered set of server addresses for each region. Addresses are received in batches but returning a completely unfiltered set will still take a long time and be prone to timeouts.

Note

If a request times out then the iterator will terminate early. Previous versions would propagate a NoResponseError.

See find() for making filtered requests.

find(region='all', **filters)

Find servers for a particular region and set of filtering rules

This returns an iterator which yields (host, port) server addresses from the master server.

region spcifies what regions to restrict the search to. It can either be a REGION_ constant or a string identifying the region. Alternately a list of the strings or REGION_ constants can be used for specifying multiple regions.

The following region identification strings are supported:

String Region(s)
na-east East North America
na-west West North America
na East North American, West North America
sa South America
eu Europe
as Asia, the Middle East
oc Oceania/Australia
af Africa
rest Unclassified servers
all All of the above

Note

rest” corresponds to all servers that don’t fit with any other region. What causes a server to be placed in this region by the master server isn’t entirely clear.

The region strings are not case sensitive. Specifying an invalid region identifier will raise a ValueError.

As well as region-based filtering, alternative filters are supported which are documented on the Valve developer wiki.

https://developer.valvesoftware.com/wiki/Master_Server_Query_Protocol#Filter

This method accepts keyword arguments which are used for building the filter string that is sent along with the request to the master server. Below is a list of all the valid keyword arguments:

Filter Description
type Server type, e.g. “dedicated”. This can be a ServerType instance or any value that can be converted to a ServerType.
secure Servers using Valve anti-cheat (VAC). This should be a boolean.
gamedir A string specifying the mod being ran by the server. For example: tf, cstrike, csgo, etc..
map Which map the server is running.
linux Servers running on Linux. Boolean.
empty Servers which are not empty. Boolean.
full Servers which are full. Boolean.
proxy SourceTV relays only. Boolean.
napp Servers not running the game specified by the given application ID. E.g. 440 would exclude all TF2 servers.
noplayers Servers that are empty. Boolean
white Whitelisted servers only. Boolean.
gametype Server which match all the tags given. This should be set to a list of strings.
gamedata Servers which match all the given hidden tags. Only applicable for L4D2 servers.
gamedataor Servers which match any of the given hidden tags. Only applicable to L4D2 servers.

Note

Your mileage may vary with some of these filters. There’s no real guarantee that the servers returned by the master server will actually satisfy the filter. Because of this it’s advisable to explicitly check for compliance by querying each server individually. See valve.source.a2s.

Example

In this example we will list all European and Asian Team Fortress 2 servers running the map ctf_2fort and print out their addresses.

import valve.source.master_server

msq = valve.source.master_server.MasterServerQuerier()
for address in msq.find(
        region=["eu", "as"], gamedir="tf", map="ctf_2fort"):
    print "{0}:{1}".format(*address)