Matchmaking API: Difference between revisions

From Official Factorio Wiki
Jump to navigation Jump to search
(Removed {{Languages}})
 
(20 intermediate revisions by 3 users not shown)
Line 1: Line 1:
{{Languages}}
<div align="center" class="stub">'''Category:''' [[Factorio_HTTP_API_usage_guidelines#Internal|Internal API]]</div>


The matchmaking API allows Factorio servers to advertise themselves, and for players to browse open game servers. The matchmaking server currently uses [https://www.heroku.com/ Heroku] and [http://gunicorn.org/ Green Unicorn] software.
The matchmaking API allows Factorio servers to advertise themselves, and for players to browse open game servers. The matchmaking server currently uses [https://www.heroku.com/ Heroku] and [http://gunicorn.org/ Green Unicorn] software.
Line 5: Line 5:
<code>API root: https://multiplayer.factorio.com/</code>
<code>API root: https://multiplayer.factorio.com/</code>


Some of the API endpoints require the use of an authentication token, which is obtained through the [[Web Authentication API]]. It is sent as the HTTP parameter named <code>token</code> and encoded using hexadecimal. For GET requests it is sent as part of the URL, and for POST requests it is sent as a POST parameter.
Some of the API endpoints require the use of an authentication token, which is obtained through the [[Web Authentication API]]. It is sent as the HTTP parameter named <code>token</code> and encoded using hexadecimal. All requests are encoded as JSON objects.


Work in progress! I'm just going to jot down some random notes in the mean time :P
Work in progress! I'm just going to jot down some random notes in the mean time :P
Line 19: Line 19:
https://multiplayer.factorio.com/remove-game/
https://multiplayer.factorio.com/remove-game/


=== Object Types ===
== Object Types ==


==== Server Description Object ====
=== Server Description Object ===


{| class="wikitable"
{| class="wikitable"
! rowspan="2" | Key
! rowspan="1" | Key
! rowspan="2" | Type
! rowspan="1" | Type
! colspan="3" | Endpoints
!+ style='writing-mode:vertical-lr;vertical-align:bottom;font-size:80.9%' | get-games
! rowspan="2" | Description
!+ style='writing-mode:vertical-lr;vertical-align:bottom;font-size:80.9%' | get-game-details
|-
!+ style='writing-mode:vertical-lr;vertical-align:bottom;font-size:80.9%' | create-game
! get
! rowspan="1" | Description
! details
! create
|-
|-
| application_version
| application_version
Line 48: Line 46:
|-
|-
| game_id
| game_id
| number
| integer
| ✓
| ✓
| ✓
| ✓
| ✓
| ✓
| A unique id generated by the matchmaking server to identify a server for the get-game-details, post-game-heartbeat, and remove-game endpoints.  
| A unique id generated by the matchmaking server to identify a server for other API endpoints.  
|-
|-
| game_secret
| game_secret
Line 62: Line 60:
|-
|-
| game_time_elapsed
| game_time_elapsed
| string(number)
| string(integer)
| ✓
| ✓
| ✓
| ✓
Line 90: Line 88:
|-
|-
| max_players
| max_players
| string(number)
| string(integer)
| ✓
| ✓
| ✓
| ✓
| ✓
| ✓
| Maximum number of players allowed to connect at once.
| Maximum number of players allowed to connect at once. 0 = unlimited.
|-
|-
| mod_count
| mod_count
| number
| integer
| ✓
| ✓
|  
|  
Line 111: Line 109:
|-
|-
| mods_crc
| mods_crc
| number
| integer
|  
|  
| ✓
| ✓
Line 133: Line 131:
| require_user_verification
| require_user_verification
| string(boolean)
| string(boolean)
|
| ✓
| ✓
| ✓
| ✓
|  
| ✓
| "true" if the server requires the user to be logged in to join.
|-
|-
| server_id
| server_id
Line 153: Line 151:
|}
|}


==== Application Version ====  
=== Application Version ===


{| class="wikitable"
{| class="wikitable"
Line 165: Line 163:
|-
|-
| build_version
| build_version
| string(number)
| string(integer)
|  
| The build version associated with the game version.
|-
|-
| game_version
| game_version
Line 174: Line 172:
| platform
| platform
| string
| string
| OS the server is running on. "linux64" for Linux, "mac" for Mac OS X, and "win64" for Windows.
| OS the server is running on: "linux64", "mac", or "win64".
|}
|}


==== Mod Description ====
=== Mod Description ===


{| class="wikitable"
{| class="wikitable"
Line 192: Line 190:
| Version string of the mod.
| Version string of the mod.
|}
|}
=== Error Message ===
This object is returned whenever there's been an error with your request.
{| class="wikitable"
! Key
! Type
! Description
|-
| message
| string
| A short description of the error.
|}
== Endpoints ==
=== get-games ===
<code>GET https://multiplayer.factorio.com/get-games</code>
Returns the available Factorio game servers as a list of [[#Server Description Object|Server Description Objects]], but only with the object keys marked as available in the "get-games" column. Requires two GET parameters:
{| class="wikitable"
| username || The factorio username associated with the auth token.
|-
| token || A valid auth token, as obtained using the [[Web Authentication API]].
|}
'''Exceptions'''
* "Missing username."
* "User not found."
* "Token doesn't match."
=== get-game-details ===
<code>GET https://multiplayer.factorio.com/get-game-details/<nowiki>{game_id}</nowiki></code>
Returns more details about the server, where {game_id} is the server's game_id as seen in the response from the get-games endpoint. This endpoint doesn't require an authentication token.


[[Category:Technical]]
[[Category:Technical]]

Latest revision as of 09:06, 12 November 2023

Category: Internal API

The matchmaking API allows Factorio servers to advertise themselves, and for players to browse open game servers. The matchmaking server currently uses Heroku and Green Unicorn software.

API root: https://multiplayer.factorio.com/

Some of the API endpoints require the use of an authentication token, which is obtained through the Web Authentication API. It is sent as the HTTP parameter named token and encoded using hexadecimal. All requests are encoded as JSON objects.

Work in progress! I'm just going to jot down some random notes in the mean time :P

https://multiplayer.factorio.com/get-games

https://multiplayer.factorio.com/get-game-details/ Unauthenticated

https://multiplayer.factorio.com/create-game

https://multiplayer.factorio.com/post-game-heartbeat/

https://multiplayer.factorio.com/remove-game/

Object Types

Server Description Object

Key Type get-games get-game-details create-game Description
application_version object ✓ ✓ ✓ See application version below.
description string ✓ ✓ The server's description.
game_id integer ✓ ✓ ✓ A unique id generated by the matchmaking server to identify a server for other API endpoints.
game_secret string ✓
game_time_elapsed string(integer) ✓ ✓ ✓ Number of in-game minutes the loaded map has elapsed.
has_password string(boolean) ✓ ✓ ✓ "true" if a password is required to join the server.
host_address string(ip:port) ✓ ✓ The IP address and port number the game server is hosted on.
last_heartbeat number ✓ The Unix timestamp of when the game server was last heard from.
max_players string(integer) ✓ ✓ ✓ Maximum number of players allowed to connect at once. 0 = unlimited.
mod_count integer ✓ Number of mods installed on the server.
mods object[] ✓ ✓ List of mods and their versions installed on the server.
mods_crc integer ✓
name string ✓ ✓ ✓ Server's name.
players string[] ✓ ✓ List of player's usernames connected to the server.
require_user_verification string(boolean) ✓ ✓ ✓ "true" if the server requires the user to be logged in to join.
server_id string ✓ ✓
tags string[] ✓ ✓ List of server tags.

Application Version

Key Type Description
build_mode string "alpha", "headless", or "steam".
build_version string(integer) The build version associated with the game version.
game_version string Game version running on the server, e.g. "0.14.21".
platform string OS the server is running on: "linux64", "mac", or "win64".

Mod Description

Key Type Description
name string ID of the mod.
version string Version string of the mod.

Error Message

This object is returned whenever there's been an error with your request.

Key Type Description
message string A short description of the error.

Endpoints

get-games

GET https://multiplayer.factorio.com/get-games

Returns the available Factorio game servers as a list of Server Description Objects, but only with the object keys marked as available in the "get-games" column. Requires two GET parameters:

username The factorio username associated with the auth token.
token A valid auth token, as obtained using the Web Authentication API.

Exceptions

  • "Missing username."
  • "User not found."
  • "Token doesn't match."

get-game-details

GET https://multiplayer.factorio.com/get-game-details/{game_id}

Returns more details about the server, where {game_id} is the server's game_id as seen in the response from the get-games endpoint. This endpoint doesn't require an authentication token.

Retrieved from "https://wiki.factorio.com/index.php?title=Matchmaking_API&oldid=195194"