In other languages:

Mod portal API: Difference between revisions

From Official Factorio Wiki
Jump to navigation Jump to search
(42 intermediate revisions by 8 users not shown)
Line 1: Line 1:
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.
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.


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


== Object Types ==
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 ==


=== Result Entry ===
=== /api/mods ===


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


{| class="wikitable"
{| class="wikitable"
! Key !! Type !!+ 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
! Key !! Values !! Description
|-
|-
| created_at || String(ISO 8601) || ✓ || ✓
| 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
| The datetime the mod was uploaded, in the full ISO 8601 format, with a space separator instead of 'T'.
|-
|-
| current_user_rating || Null || ✓ ||
| page_size ||{an integer or 'max'}||The amount of results to show in your search
| Doesn't seem to be implemented yet.
|-
|-
| description || String || || ✓
| namelist || {array of strings} || Return only mods that match the given names.
| A longer description of the mod, in text only format.
|}
 
 
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
|-
|-
| description_html || String(HTML) || || ✓
| pagination || [[#Pagination|Pagination]] || See [[#Pagination]]
| A longer description of the mod, with HTML tags.
|-
|-
| downloads_count || Integer || ||
| results || [[#Result Entry|Result]][] || A list of mods, matching any filters you specified.
| Number of downloads.
|}
 
=== Pagination ===
 
{| class="wikitable"
! Key !! Type !! Description
|-
|-
| first_media_file || Object || ✓ ||
| count || Integer || Total number of mods that match your specified filters.
| The first media file in the "media_files" list.
|-
|-
| game_versions || String[] || ✓ || ✓
| links || [[#Pagination_Links|Links]] || Utility links to mod portal api requests, preserving all filters and search queries.
| A list of major Factorio version strings (e.g. "0.13") starting with 0.13 that the mod is compatible with, ''in addition to'' the version(s) found in "latest_release" / "releases".  
|-
|-
| github_path || String || ||
| page || Integer || The current page number.
| A link to the mod's github project page, just prepend "github.com/". Can be blank ("").
|-
|-
| homepage || String || ✓ || ✓
| page_count || Integer || The total number of pages returned.
| Usually a URL to the mod's main project page, but can be any string.
|-
|-
| id || Integer || ||
| page_size || Integer || The number of results per page.
| A numerical mod ID used to identify the mod in other API endpoints.
|}
 
=== Pagination Links ===
 
{| class="wikitable"
! Key !! Type !! Description
|-
|-
| latest_release || Object || ||  
| first || String(URL) || URL to the first page of the results, or null if you're already on the first page.
| The latest version of the mod available for download. See [[#Releases]]
|-
| prev || String(URL) || URL to the previous page of the results, or null if you're already on the first page.
|-
|-
| license_flags || Integer(11 bit) || ✓ || ✓
| next || String(URL) || URL to the next page of the results, or null if you're already on the last page.
| A bit field describing what permissions the mod's license grants. See [[#License Flags]]
|-
|-
| license_name || String || ✓ ||
| last || String(URL) || URL to the last page of the results, or null if you're already on the last page.
| The mod's license name.
|}
 
=== 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
|-
|-
| license_url || String || ✓ || ✓
| downloads_count || Integer || ✓ || ✓ || ✓
| A URL link to the full license agreement. Can be any string in case of custom licenses.
| Number of downloads.
|-
|-
| media_files || Object[] || ||
| latest_release || [[#Releases|Release]] || ✓ || ||
| A list of media files, such as screen shots of the mod in action. See [[#Media Files]].
| The latest version of the mod available for download. See [[#Releases]]
|-
|-
| name || String || ✓ || ✓
| name || String || ✓ || ✓ || ✓
| The mod's machine-readable ID string.
| The mod's machine-readable ID string.
|-
|-
| owner || String || ✓ || ✓
| owner || String || ✓ || ✓ || ✓
| The Factorio username of the mod's author.
| The Factorio username of the mod's author.
|-
|-
| ratings_count || 0 || || ✓
| releases || [[#Releases|Release]][] || || ✓ || ✓
| Doesn't seem to be implemented yet.
|-
| releases || Object[] || || ✓
| A list of different versions of the mod available for download. See [[#Releases]]
| A list of different versions of the mod available for download. See [[#Releases]]
|-
|-
| summary || String || ✓ || ✓
| summary || String || ✓ || ✓ || ✓
| A shorter mod description.
| A shorter mod description.
|-
|-
| tags || Object[] || ✓ || ✓
| title || String || ✓ || ✓ || ✓
| A list of tag objects that categorize the mod.
| 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 ("").
|-
|-
| title || String || || ✓
| homepage || String || || || ✓
| The mod's human-readable name.
| Usually a URL to the mod's main project page, but can be any string.
|-
|-
| updated_at || String(ISO 8601) || || ✓
| tag || [[#Tags|Tag]][] || || || ✓
| The datetime the mod was last updated, in the full ISO 8601 format, with a space separator instead of 'T'.
| A list of tag objects that categorize the mod. See [[#Tags]].
|-
|-
| visits_count || Integer || ✓ || ✓
| The number of times the mod was viewed, but perhaps only counted on the web interface???
|}
|}


=== License Flags ===
=== Releases ===


The "license_flags" is an 11 bit number that describe generally what permissions the mod's license grants.
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"
{| class="wikitable"
! 2<sup>n</sup> !! Title !! Description
! Key !! Type !! Description
|-
|-
! colspan=3 | Permissions
| download_url || String
| Path to download for a mod. starts with "/download" and does not include a full url. See [[#Downloading Mods]]
|-
|-
| 0 || Commercial Use || This software and derivatives may be used for commercial purposes
| file_name || String
| The file name of the release. Always seems to follow the pattern "{name}_{version}.zip"
|-
|-
| 1 || Modification || The software may be modified.
| 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.
|-
|-
| 2 || Distribution || You may distribute this software.
| version || String
| The version string of this mod release. Used to determine dependencies.  
|-
|-
| 3 || Patent Use || This license provides an express grant of patent rights from the contributor to the recipient.
| sha1 || String
| The sha1 key for the file
|-
|}
 
=== Tags ===
 
{| class="wikitable"
! Key !! Type !! Description
|-
|-
| 4 || Private Use || You may use and modify the software without distributing it.
| id || Integer || A numerical ID unique to this tag.
|-
|-
! colspan=3 | Conditions
| name || String || An all lower-case string used to identify this tag internally.
|-
|-
| 5 || Disclose Source || Source code must be made available when distributing the software.
| title || String || The tag's human-readable tag name.
|-
|-
| 6 || License & Copyright Notice || Include a copy of the license and copyright notice with the code.
| description || String || A short description for the tag.
|-
|-
| 7 || Same License || Modifications must be released under the same license when distributing the software. In some cases a similar or related license may be used.
| type || String ||  
|}
 
Currently, there are only a fixed number of tags available, these include:
 
{| class="wikitable"
! id !! type !! name !! title !! description
|-
|-
| 8 || State Changes || Indicate changes made to the code.
| 1 || t || general || General || Mods that cannot be sorted into other categories
|-
|-
! colspan=3 | Limitations
| 2 || t || non-game-changing || Non-Game-Changing || Changes only look&feel. New graphics, new sounds, ... such things.
|-
|-
| 9 || Hold Liable || Software is provided without warranty and the software author/license owner cannot be held liable for damages.
| 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...
|-
|-
| 10 || Trademark Use || This license explicitly states that it does NOT grant you trademark rights, even though licenses without such a statement probably do not grant you any implicit trademark rights.
| 6 || t || big-mods || Big Mods || Too big and/or changes too much of the game to be fit anywhere else
|}
 
=== Media File ===
 
A media file object describes a single image, along with a smaller thumbnail sized version of the image.
 
{| class="wikitable"
! Key !! Type !! Description
|-
|-
| id || Integer || A numerical ID unique to this media file.
| 12 || t || transportation || Transportation || Player transport
|-
|-
| width || Integer || Width of the full sized image in pixels.
| 13 || t || logistics || Logistics || Transport of materials
|-
|-
| height || Integer || Height of the full sized image in pixels.
| 14 || t || utility || Utility || Helps with certain things the player is doing.
|-
|-
| size || Integer || Size of the full image in bytes.
| 15 || t || balancing || Balancing || Makes the game much more fair
|-
|-
| urls || Object || URLs to the full sized image and a thumbnail, see below.
| 17 || t || enemies || Enemies || Adds more enemies for more challange
|}
 
The "urls" object contains two keys: "original" that links to the original, full sized image, and "thumb" that links to a 144x144 pixel PNG image. The original image is in either PNG, JPEG, or GIF formats, with the extensions ".png", ".jpg", or ".gif". All image URLs seem to be located at https://mods-data.factorio.com/pub_data/media_files/ with a file name consisting of 12 alphanumerical characters (of the base64 alphabet) followed by the file extension. The thumbnail URL contains the same code, but instead with a file extension of ".thumb.png".
 
=== Releases ===
 
{| class="wikitable"
! Key !! Type !! Description
|-
|-
| download_url || String ||
| 16 || t || weapons || Weapons || Adds more weapons to annihilate the enemy
|-
|-
| downloads_count || Integer ||
| 18 || t || armor || Armor || Armors or armor equipment related.
|-
|-
| factorio_version || String ||
| 19 || t || oil || Oil || Things related to oil related manufacture
|-
|-
| file_name || String ||
| 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
|-
|-
| file_size || Integer ||
| 22 || t || power-production || Power Production || Allows more ways to create mass amounts of energy
|-
|-
| game_version || String ||
| 23 || t || manufacture || Manufacture || Furnaces, assembling machines, production chains
|-
|-
| id || Integer ||
| 24 || t || blueprints || Blueprints ||  
|-
|-
| info_json || Object ||
| 25 || t || cheats || Cheats || Well, they let you cheat
|-  
|-  
| released_at || String(ISO 8601) ||  
| 26 || t || defense || Defense || Mods that add the ability to protect your base more
|-
|-
| version || String ||
| 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]]
{{Languages}}[[Category:Technical]]

Revision as of 09:43, 12 August 2020

The Mod Portal API is used to both browse and download all mods available on the 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.

https://mods.factorio.com/api/mods

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.

https://mods.factorio.com/api/mods/{name}

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

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

Endpoints

/api/mods

GET Parameters:

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

Key Type Description
pagination Pagination See #Pagination
results Result[] A list of mods, matching any filters you specified.

Pagination

Key Type Description
count Integer Total number of mods that match your specified filters.
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

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.

Key Type api/mods endpoint Short Full Description
downloads_count Integer Number of downloads.
latest_release 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 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 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 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.

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

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:

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

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.

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