Official Factorio Wiki - User contributions [en]

Mod portal API

2020-08-12T09:43:46Z

Vince: /* Result Entry */

The Mod Portal API is used to both browse and download all mods available on the [https://mods.factorio.com/ official Factorio mod portal]. Using the API does not require any kind of authentication or account information and can be viewed simply by following the URLs below in any web browser.

<code>https://mods.factorio.com/api/mods</code>

More detailed information about a particular mod can be obtained by retrieving the following URL, where {name} is the mod's name field in the result object.

<code>https://mods.factorio.com/api/mods/{name}</code>

To get even more information about a mod, you can use the following URL.

<code>https://mods.factorio.com/api/mods/{name}/full</code>

== Endpoints ==

=== /api/mods ===

GET Parameters:

{| class="wikitable"
! Key !! Values !! Description
|-
| page ||{an integer}||Page number you would like to show. Makes it so you can see a certain part of the list without getting detail on all
|-
| page_size ||{an integer or 'max'}||The amount of results to show in your search
|-
| namelist || {array of strings} || Return only mods that match the given names.
|}

Returns [[#Mod List Response]]

=== /api/mods/{mod_name} ===

Return short information of a specific mod.

See [[#Result Entry]], "Short" column.

=== /api/mods/{mod_name}/full ===

Returns more information of a mod.

See [[#Result Entry]], "Full" column.

== JSON Object Types ==

=== Mod List Response ===

{| class="wikitable"
! Key !! Type !! Description
|-
| pagination || [[#Pagination|Pagination]] || See [[#Pagination]]
|-
| results || [[#Result Entry|Result]][] || A list of mods, matching any filters you specified.
|}

=== Pagination ===

{| class="wikitable"
! Key !! Type !! Description
|-
| count || Integer || Total number of mods that match your specified filters.
|-
| links || [[#Pagination_Links|Links]] || Utility links to mod portal api requests, preserving all filters and search queries.
|-
| page || Integer || The current page number.
|-
| page_count || Integer || The total number of pages returned.
|-
| page_size || Integer || The number of results per page.
|}

=== Pagination Links ===

{| class="wikitable"
! Key !! Type !! Description
|-
| first || String(URL) || URL to the first page of the results, or null if you're already on the first page.
|-
| prev || String(URL) || URL to the previous page of the results, or null if you're already on the first page.
|-
| next || String(URL) || URL to the next page of the results, or null if you're already on the last page.
|-
| last || String(URL) || URL to the last page of the results, or null if you're already on the last page.
|}

=== Result Entry ===

Fields returned by the api/mods endpoint are marked with a check (✓) in the "api/mods endpoint" column, those returned by the api/mods/{name} endpoint are marked with a check in the "Short" column and those returned by the api/mods/{name}/full endpoint are marked in the "Full" column.

{| class="wikitable"
! Key !! Type !!+ style='writing-mode:vertical-lr;vertical-align:bottom;font-size:90%' | api/mods endpoint !!+ style='writing-mode:vertical-lr;vertical-align:bottom;font-size:90%' | Short !!+ style='writing-mode:vertical-lr;vertical-align:bottom;font-size:90%' | Full !! Description
|-
| downloads_count || Integer || ✓ || ✓ || ✓
| Number of downloads.
|-
| latest_release || [[#Releases|Release]] || ✓ || ||
| The latest version of the mod available for download. See [[#Releases]]
|-
| name || String || ✓ || ✓ || ✓
| The mod's machine-readable ID string.
|-
| owner || String || ✓ || ✓ || ✓
| The Factorio username of the mod's author.
|-
| releases || [[#Releases|Release]][] || || ✓ || ✓
| A list of different versions of the mod available for download. See [[#Releases]]
|-
| summary || String || ✓ || ✓ || ✓
| A shorter mod description.
|-
| title || String || ✓ || ✓ || ✓
| The mod's human-readable name.
|-
| category || [[#Tags|Tag]]? || ✓ || ✓ || ✓
| A single tag describing the mod. Warning: Seems to be absent sometimes. See [[#Tags]].
|-
| changelog || String || || || ✓
| A string describing the recent changes to a mod
|-
| created_at || String(ISO 8601) || || || ✓
| ISO 6501 for when the mod was created.
|-
| description || String || || || ✓
| A longer description of the mod, in text only format.
|-
| github_path || String || || || ✓
| A link to the mod's github project page, just prepend "github.com/". Can be blank ("").
|-
| homepage || String || || || ✓
| Usually a URL to the mod's main project page, but can be any string.
|-
| tag || [[#Tags|Tag]][] || || || ✓
| A list of tag objects that categorize the mod. See [[#Tags]].
|-
|}

=== Releases ===

Only difference here between the api/mods/{name} endpoint and the api/mods/{name}/full endpoint is that the full one includes an array of dependencies in the info_json object.

{| class="wikitable"
! Key !! Type !! Description
|-
| download_url || String
| Path to download for a mod. starts with "/download" and does not include a full url. See [[#Downloading Mods]]
|-
| file_name || String
| The file name of the release. Always seems to follow the pattern "{name}_{version}.zip"
|-
| info_json || Object
| A copy of the mod's info.json file, only contains factorio_version in short version, also contains an array of dependencies in full version
|-
| released_at || String(ISO 8601)
| ISO 6501 for when the mod was released.
|-
| version || String
| The version string of this mod release. Used to determine dependencies.
|-
| sha1 || String
| The sha1 key for the file
|-
|}

=== Tags ===

{| class="wikitable"
! Key !! Type !! Description
|-
| id || Integer || A numerical ID unique to this tag.
|-
| name || String || An all lower-case string used to identify this tag internally.
|-
| title || String || The tag's human-readable tag name.
|-
| description || String || A short description for the tag.
|-
| type || String ||
|}

Currently, there are only a fixed number of tags available, these include:

{| class="wikitable"
! id !! type !! name !! title !! description
|-
| 1 || t || general || General || Mods that cannot be sorted into other categories
|-
| 2 || t || non-game-changing || Non-Game-Changing || Changes only look&feel. New graphics, new sounds, ... such things.
|-
| 3 || t || helper-mods || Helper Mods || These mods are not game-changing, but enhance the gameplay by helping you with useful functions. Mods like showing the current game-time, keep track over your resources, rail-laying...
|-
| 6 || t || big-mods || Big Mods || Too big and/or changes too much of the game to be fit anywhere else
|-
| 12 || t || transportation || Transportation || Player transport
|-
| 13 || t || logistics || Logistics || Transport of materials
|-
| 14 || t || utility || Utility || Helps with certain things the player is doing.
|-
| 15 || t || balancing || Balancing || Makes the game much more fair
|-
| 17 || t || enemies || Enemies || Adds more enemies for more challange
|-
| 16 || t || weapons || Weapons || Adds more weapons to annihilate the enemy
|-
| 18 || t || armor || Armor || Armors or armor equipment related.
|-
| 19 || t || oil || Oil || Things related to oil related manufacture
|-
| 20 || t || logistics-network || Logistics Network || Related to roboports and logistic robots
|-
| 21 || t || storage || Storage || Allows more ways to be able to store items
|-
| 22 || t || power-production || Power Production || Allows more ways to create mass amounts of energy
|-
| 23 || t || manufacture || Manufacture || Furnaces, assembling machines, production chains
|-
| 24 || t || blueprints || Blueprints ||
|-
| 25 || t || cheats || Cheats || Well, they let you cheat
|-
| 26 || t || defense || Defense || Mods that add the ability to protect your base more
|-
| 27 || t || mining || Mining || Mods that provide better or new ways of mining resources
|-
| 28 || t || info || Info || Mods that provide additional information to the player
|-
| 29 || t || trains || Trains || Related to trains
|}

=== Error ===

{| class="wikitable"
! Key !! Type !! Description
|-
| detail || String ||
|}

== Downloading Mods ==

You can get the full url by appending the download_url to mods.factorio.com, but if you're not authenticated, you will be redirected to mods.factorio.com/login. Logging in to that would give you access to the file. Fortunately, there's a better way to do this. Simply adding username and token parameters to the download url will prevent the redirecting and let you download the file immediately. The token can be acquired from a json file called "player-data.json", located in the User Data directory (see [[Application_directory#User_data_directory]]). You can also get the token by using the [[Web_authentication_API | Web Authentication API]].

Example usage:
https://mods.factorio.com/{download_url}?username={username}&token={token}

{{Languages}}[[Category:Technical]]

Mod portal API

2020-08-12T09:43:03Z

Vince: /* Result Entry */

The Mod Portal API is used to both browse and download all mods available on the [https://mods.factorio.com/ official Factorio mod portal]. Using the API does not require any kind of authentication or account information and can be viewed simply by following the URLs below in any web browser.

<code>https://mods.factorio.com/api/mods</code>

More detailed information about a particular mod can be obtained by retrieving the following URL, where {name} is the mod's name field in the result object.

<code>https://mods.factorio.com/api/mods/{name}</code>

To get even more information about a mod, you can use the following URL.

<code>https://mods.factorio.com/api/mods/{name}/full</code>

== Endpoints ==

=== /api/mods ===

GET Parameters:

{| class="wikitable"
! Key !! Values !! Description
|-
| page ||{an integer}||Page number you would like to show. Makes it so you can see a certain part of the list without getting detail on all
|-
| page_size ||{an integer or 'max'}||The amount of results to show in your search
|-
| namelist || {array of strings} || Return only mods that match the given names.
|}

Returns [[#Mod List Response]]

=== /api/mods/{mod_name} ===

Return short information of a specific mod.

See [[#Result Entry]], "Short" column.

=== /api/mods/{mod_name}/full ===

Returns more information of a mod.

See [[#Result Entry]], "Full" column.

== JSON Object Types ==

=== Mod List Response ===

{| class="wikitable"
! Key !! Type !! Description
|-
| pagination || [[#Pagination|Pagination]] || See [[#Pagination]]
|-
| results || [[#Result Entry|Result]][] || A list of mods, matching any filters you specified.
|}

=== Pagination ===

{| class="wikitable"
! Key !! Type !! Description
|-
| count || Integer || Total number of mods that match your specified filters.
|-
| links || [[#Pagination_Links|Links]] || Utility links to mod portal api requests, preserving all filters and search queries.
|-
| page || Integer || The current page number.
|-
| page_count || Integer || The total number of pages returned.
|-
| page_size || Integer || The number of results per page.
|}

=== Pagination Links ===

{| class="wikitable"
! Key !! Type !! Description
|-
| first || String(URL) || URL to the first page of the results, or null if you're already on the first page.
|-
| prev || String(URL) || URL to the previous page of the results, or null if you're already on the first page.
|-
| next || String(URL) || URL to the next page of the results, or null if you're already on the last page.
|-
| last || String(URL) || URL to the last page of the results, or null if you're already on the last page.
|}

=== Result Entry ===

Fields returned by the api/mods endpoint are marked with a check (✓) in the "api/mods endpoint" column, those returned by the api/mods/{name} endpoint are marked with a check in the "Short" column and those returned by the api/mods/{name}/full endpoint are marked in the "Full" column.

{| class="wikitable"
! Key !! Type !!+ style='writing-mode:vertical-lr;vertical-align:bottom;font-size:90%' | api/mods endpoint !!+ style='writing-mode:vertical-lr;vertical-align:bottom;font-size:90%' | Short !!+ style='writing-mode:vertical-lr;vertical-align:bottom;font-size:90%' | Full !! Description
|-
| downloads_count || Integer || ✓ || ✓ || ✓
| Number of downloads.
|-
| latest_release || [[#Releases|Release]] || ✓ || ||
| The latest version of the mod available for download. See [[#Releases]]
|-
| name || String || ✓ || ✓ || ✓
| The mod's machine-readable ID string.
|-
| owner || String || ✓ || ✓ || ✓
| The Factorio username of the mod's author.
|-
| releases || [[#Releases|Release]][] || || ✓ || ✓
| A list of different versions of the mod available for download. See [[#Releases]]
|-
| summary || String || ✓ || ✓ || ✓
| A shorter mod description.
|-
| title || String || ✓ || ✓ || ✓
| The mod's human-readable name.
|-
| category || String || ✓ || ✓ || ✓
| A single tag describing the mod. Warning: Seems to be absent sometimes. See [[#Tags]].
|-
| changelog || String || || || ✓
| A string describing the recent changes to a mod
|-
| created_at || String(ISO 8601) || || || ✓
| ISO 6501 for when the mod was created.
|-
| description || String || || || ✓
| A longer description of the mod, in text only format.
|-
| github_path || String || || || ✓
| A link to the mod's github project page, just prepend "github.com/". Can be blank ("").
|-
| homepage || String || || || ✓
| Usually a URL to the mod's main project page, but can be any string.
|-
| tag || [[#Tags|Tag]][] || || || ✓
| A list of tag objects that categorize the mod. See [[#Tags]].
|-
|}

=== Releases ===

Only difference here between the api/mods/{name} endpoint and the api/mods/{name}/full endpoint is that the full one includes an array of dependencies in the info_json object.

{| class="wikitable"
! Key !! Type !! Description
|-
| download_url || String
| Path to download for a mod. starts with "/download" and does not include a full url. See [[#Downloading Mods]]
|-
| file_name || String
| The file name of the release. Always seems to follow the pattern "{name}_{version}.zip"
|-
| info_json || Object
| A copy of the mod's info.json file, only contains factorio_version in short version, also contains an array of dependencies in full version
|-
| released_at || String(ISO 8601)
| ISO 6501 for when the mod was released.
|-
| version || String
| The version string of this mod release. Used to determine dependencies.
|-
| sha1 || String
| The sha1 key for the file
|-
|}

=== Tags ===

{| class="wikitable"
! Key !! Type !! Description
|-
| id || Integer || A numerical ID unique to this tag.
|-
| name || String || An all lower-case string used to identify this tag internally.
|-
| title || String || The tag's human-readable tag name.
|-
| description || String || A short description for the tag.
|-
| type || String ||
|}

Currently, there are only a fixed number of tags available, these include:

{| class="wikitable"
! id !! type !! name !! title !! description
|-
| 1 || t || general || General || Mods that cannot be sorted into other categories
|-
| 2 || t || non-game-changing || Non-Game-Changing || Changes only look&feel. New graphics, new sounds, ... such things.
|-
| 3 || t || helper-mods || Helper Mods || These mods are not game-changing, but enhance the gameplay by helping you with useful functions. Mods like showing the current game-time, keep track over your resources, rail-laying...
|-
| 6 || t || big-mods || Big Mods || Too big and/or changes too much of the game to be fit anywhere else
|-
| 12 || t || transportation || Transportation || Player transport
|-
| 13 || t || logistics || Logistics || Transport of materials
|-
| 14 || t || utility || Utility || Helps with certain things the player is doing.
|-
| 15 || t || balancing || Balancing || Makes the game much more fair
|-
| 17 || t || enemies || Enemies || Adds more enemies for more challange
|-
| 16 || t || weapons || Weapons || Adds more weapons to annihilate the enemy
|-
| 18 || t || armor || Armor || Armors or armor equipment related.
|-
| 19 || t || oil || Oil || Things related to oil related manufacture
|-
| 20 || t || logistics-network || Logistics Network || Related to roboports and logistic robots
|-
| 21 || t || storage || Storage || Allows more ways to be able to store items
|-
| 22 || t || power-production || Power Production || Allows more ways to create mass amounts of energy
|-
| 23 || t || manufacture || Manufacture || Furnaces, assembling machines, production chains
|-
| 24 || t || blueprints || Blueprints ||
|-
| 25 || t || cheats || Cheats || Well, they let you cheat
|-
| 26 || t || defense || Defense || Mods that add the ability to protect your base more
|-
| 27 || t || mining || Mining || Mods that provide better or new ways of mining resources
|-
| 28 || t || info || Info || Mods that provide additional information to the player
|-
| 29 || t || trains || Trains || Related to trains
|}

=== Error ===

{| class="wikitable"
! Key !! Type !! Description
|-
| detail || String ||
|}

== Downloading Mods ==

You can get the full url by appending the download_url to mods.factorio.com, but if you're not authenticated, you will be redirected to mods.factorio.com/login. Logging in to that would give you access to the file. Fortunately, there's a better way to do this. Simply adding username and token parameters to the download url will prevent the redirecting and let you download the file immediately. The token can be acquired from a json file called "player-data.json", located in the User Data directory (see [[Application_directory#User_data_directory]]). You can also get the token by using the [[Web_authentication_API | Web Authentication API]].

Example usage:
https://mods.factorio.com/{download_url}?username={username}&token={token}

{{Languages}}[[Category:Technical]]

Download API

2020-08-12T09:28:59Z

Vince: /* Version Listings */

This API allows you to download official releases of stand-alone Factorio from the Factorio servers. It's not so much of an API as it is web scraping, but it's documented here for completeness. Please update this page if you utilize it and the information becomes outdated. Also note that's there's a separate, (semi)official API for upgrading between releases, which should be used when possible to lighten the load on the Factorio servers. (I'll document that later, promise!)

== Authenticating ==

Downloading Factorio requires an authenticated session with the web server, which is different than the typical API authentication mechanism. Authentication uses the HTML endpoint at

<code>https://www.factorio.com/login</code>

Login in procedure:

# Create an HTTP session and send a GET request. You'll get some HTML in return.<br>There's a [[:Wikipedia:Cross-site_request_forgery#Synchronizer_token_pattern|CSRF token]] you'll need to grab which can be found using one of the following selectors:
#* CSS1: <code>input[name=csrf_token]</code> (and then take the "value" attribute).
#* XPATH1: <code>//input[@name="csrf_token"]/@value</code>
# Then send a POST request with the following parameters:
#* <code>csrf_token</code>: the CSRF token you grabbed earlier.
#* <code>username_or_email</code>: your username or email address.
#* <code>password</code>: your password.

== Downloading ==

Download Factorio releases at

<code>https://www.factorio.com/get-download/{version}/{build}/{distro}</code>

* Where {version} is the version string of the release you wish to grab - e.g. "0.15.31". Use "latest" instead to default to the latest version for that build.
* {build} is the release build, which currently comprises of:
** <code>alpha</code> - the current standard full-featured build.
** <code>demo</code> - the free, publicly accessible demo versions.
** <code>headless</code> - for running servers on machines without graphical interface.
* and {distro} is the os / type of release you wish to download, currently:
** <code>win64</code> - EXE installer for 64 bit Windows.
** <code>win64-manual</code> - ZIP package for 64 bit Windows.
** <code>win32</code> - EXE installer for 32 bit Windows. ''No longer supported.''
** <code>win32-manual</code> - ZIP package for 32 bit Windows. ''No longer supported.''
** <code>osx</code> - DMG package for 64 bit Mac OS.
** <code>linux64</code> - tar.gz or tar.xz package for 64 bit Linux.
** <code>linux32</code> - tar.gz or tar.xz package for 32 bit Linux. ''No longer supported.''

Factorio servers will correctly respond with a 404 if the requested download isn't available. Experimental builds are taken down quickly after they become obsolete, so it's best to check what versions are available before hand (documented below).

Note: Windows 32 bit and 64 bit installers are [https://en.wikipedia.org/wiki/Inno_Setup Inno Setup] formatted packages (I'll document that somewhere someday).

== Version Listings ==
There is an API endpoint to find the latest version number at <code>https://factorio.com/api/latest-releases</code>. This can be polled to automatically detect when a new update was released.

Due to changes in the Factorio website, all Factorio versions are now available on the HTML page at this location:

<code>https://www.factorio.com/download/archive</code>

Note: This endpoint require an authenticated session as mentioned above.

You could the grab all the informations you need by parsing the HTML using selectors but I would recommend only searching for the pattern <code>href="/get-download/*"</code> and then parse the relative link according to the <code>/get-download/{version}/{build}/{distro}</code> structure described in the section above. The second method has a clear advantage of reliability through potential HTML structure changes and simplicity.

It is also better to rely on the <code>https://factorio.com/api/latest-releases</code> endpoint and version number comparisons to distinguish between stable and experimental versions than to extract that information from the download HTML page with selectors.

The previous endpoints for experimental and headless releases <code>https://www.factorio.com/download/experimental</code> and <code>https://www.factorio.com/download-headless</code> now both redirect to this page containing only the latest releases:

<code>https://www.factorio.com/download</code>

The selectors used to retrieve version numbers and build combinations are presented below, but they are probably obsolete. I will check them later and update this section accordingly.
* CSS1: <code>h3</code>
* XPATH1: <code>//h3</code>

A list of available update packages is provided at <code>https://updater.factorio.com/get-available-versions</code>.

{{Languages}}[[Category:Technical]]

Download API

2020-08-12T09:18:50Z

Vince: /* Version Listings */

This API allows you to download official releases of stand-alone Factorio from the Factorio servers. It's not so much of an API as it is web scraping, but it's documented here for completeness. Please update this page if you utilize it and the information becomes outdated. Also note that's there's a separate, (semi)official API for upgrading between releases, which should be used when possible to lighten the load on the Factorio servers. (I'll document that later, promise!)

== Authenticating ==

Downloading Factorio requires an authenticated session with the web server, which is different than the typical API authentication mechanism. Authentication uses the HTML endpoint at

<code>https://www.factorio.com/login</code>

Login in procedure:

# Create an HTTP session and send a GET request. You'll get some HTML in return.<br>There's a [[:Wikipedia:Cross-site_request_forgery#Synchronizer_token_pattern|CSRF token]] you'll need to grab which can be found using one of the following selectors:
#* CSS1: <code>input[name=csrf_token]</code> (and then take the "value" attribute).
#* XPATH1: <code>//input[@name="csrf_token"]/@value</code>
# Then send a POST request with the following parameters:
#* <code>csrf_token</code>: the CSRF token you grabbed earlier.
#* <code>username_or_email</code>: your username or email address.
#* <code>password</code>: your password.

== Downloading ==

Download Factorio releases at

<code>https://www.factorio.com/get-download/{version}/{build}/{distro}</code>

* Where {version} is the version string of the release you wish to grab - e.g. "0.15.31". Use "latest" instead to default to the latest version for that build.
* {build} is the release build, which currently comprises of:
** <code>alpha</code> - the current standard full-featured build.
** <code>demo</code> - the free, publicly accessible demo versions.
** <code>headless</code> - for running servers on machines without graphical interface.
* and {distro} is the os / type of release you wish to download, currently:
** <code>win64</code> - EXE installer for 64 bit Windows.
** <code>win64-manual</code> - ZIP package for 64 bit Windows.
** <code>win32</code> - EXE installer for 32 bit Windows. ''No longer supported.''
** <code>win32-manual</code> - ZIP package for 32 bit Windows. ''No longer supported.''
** <code>osx</code> - DMG package for 64 bit Mac OS.
** <code>linux64</code> - tar.gz or tar.xz package for 64 bit Linux.
** <code>linux32</code> - tar.gz or tar.xz package for 32 bit Linux. ''No longer supported.''

Factorio servers will correctly respond with a 404 if the requested download isn't available. Experimental builds are taken down quickly after they become obsolete, so it's best to check what versions are available before hand (documented below).

Note: Windows 32 bit and 64 bit installers are [https://en.wikipedia.org/wiki/Inno_Setup Inno Setup] formatted packages (I'll document that somewhere someday).

== Version Listings ==
There is an API endpoint to find the latest version number at <code>https://factorio.com/api/latest-releases</code>. This can be polled to automatically detect when a new update was released.

Due to changes in the Factorio website, all Factorio versions are now available on the HTML page at this location:

<code>https://www.factorio.com/download/archive</code>

Note: This endpoint require an authenticated session as mentioned above.

You could the grab all the informations you need by parsing the HTML using selectors but I would recommend only searching for the pattern <code>href="/get-download/*"</code> and then parse the relative link according to the "/get-download/{version}/{build}/{distro}" structure described in the section above. The second method has a clear advantage of reliability through potential HTML structure changes and simplicity.

It is also better to rely on the <code>https://factorio.com/api/latest-releases</code> endpoint and version number comparisons to distinguish between stable and experimental versions than to extract that information from the download HTML page with selectors.

The previous endpoints for experimental and headless releases <code>https://www.factorio.com/download/experimental</code> and <code>https://www.factorio.com/download-headless</code> now both redirect to this page containing only the latest releases:

<code>https://www.factorio.com/download</code>

The selectors used to retrieve version numbers and build combinations are presented below, but they are probably obsolete. I will check them later and update this section accordingly.
* CSS1: <code>h3</code>
* XPATH1: <code>//h3</code>

A list of available update packages is provided at <code>https://updater.factorio.com/get-available-versions</code>.

{{Languages}}[[Category:Technical]]