Mod portal API: Difference between revisions

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


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 8: Line 8:


<code>https://mods.factorio.com/api/mods/{name}</code>
<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 ==
== Endpoints ==
TODO!!!


=== /api/mods ===
=== /api/mods ===


GET Parameters:
GET Parameters (sent as query parameters):


{| class="wikitable"
{| class="wikitable"
! Key !! Values !! Description
! Key !! Values !! Description
|-
|-
| order ||updated, alpha, top||How to order the mods, by most recently updated, alphabetically, or by most downloaded.
| hide_deprecated || {boolean} || Only return non-deprecated mods.  
|-
|-
| owner ||||
| 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 ||{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
|-
|-
| page_size ||{an integer}||The amount of results to show in your search
| sort || {enum, one of name, created_at or updated_at} || Sort results by this property. Defaults to name when not defined. Ignored for <code>page_size=max</code> queries.
|-
|-
| q ||{a string}||Name/Partial Name of mod you want to search for
| sort_order || {enum, one of asc or desc} || Sort results ascending or descending. Defaults to descending when not defined. Ignored for <code>page_size=max</code> queries.
|-
|-
| tags ||||
| namelist || {array of strings} || Return only mods that match the given names. Either comma-separated names or supply the namelist parameter more than once. Response will include <code>releases</code> instead of <code>latest_release</code>.
|-
|-
| namelist || {{array of strings} || Return only mods that match the given names.
| version || {enum, one of 0.13, 0.14, 0.15, 0.16, 0.17, 0.18, 1.0 or 1.1} || Only return non-deprecated mods compatible with this Factorio version
|}
|}


Line 40: Line 42:
=== /api/mods/{mod_name} ===
=== /api/mods/{mod_name} ===


=== /api/messages ===
Return short information of a specific mod.


GET Parameters:
See [[#Result Entry]], "Short" column.


{| class="wikitable"
=== /api/mods/{mod_name}/full ===
! Key !! Values !! Description
 
|-
Returns more information of a mod.
| page_size || {an integer} || How many messages on one page
|-
| page || {an integer} || Which page of messages
|-
| mod || {name of mod} || Name of the specific mod that you want messages for
|-
| tag || {a letter} || The letter that represents the different message tags
|}


=== /api/users ===
See [[#Result Entry]], "Full" column.


== JSON Object Types ==
== JSON Object Types ==
Line 102: Line 96:
=== Result Entry ===
=== Result Entry ===


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.
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. Fields may be absent if there is no data.


{| 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 !! 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
|-
| created_at || String(ISO 8601) || ✓ || ✓
| The datetime the mod was uploaded, in the full ISO 8601 format, with a space separator instead of 'T'.
|-
| current_user_rating || Null || ✓ || ✓
| Doesn't seem to be implemented yet. Always null.
|-
| description || String || || ✓
| A longer description of the mod, in text only format.
|-
|-
| description_html || String(HTML) || || ✓
| downloads_count || Integer || ✓ || ✓ || ✓
| A longer description of the mod, with HTML tags.
|-
| downloads_count || Integer || ✓ || ✓
| Number of downloads.
| Number of downloads.
|-
|-
| first_media_file || [[#Media Files|Media File]] || ✓ ||  
| latest_release || [[#Releases|Release]]? || ✓ || ||
| The first media file in the "media_files" list.
| The latest version of the mod available for download. Absent when the <code>namelist</code> [[#/api/mods|parameter]] is used.
|-
|-
| game_versions || String[] || ✓ || ✓
| name || String || ✓ || ✓ || ✓
| 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 || ✓ || ✓
| 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.
|-
| id || Integer || ✓ || ✓
| A numerical mod ID used to identify the mod in other API endpoints.
|-
| latest_release || [[#Releases|Release]] || ✓ ||
| The latest version of the mod available for download. See [[#Releases]]
|-
| license_flags || Integer(11 bit) || ✓ || ✓
| A bit field describing what permissions the mod's license grants. See [[#License Flags]]
|-
| license_name || String || ✓ || ✓
| The mod's license name.
|-
| license_url || String || ✓ || ✓
| A URL link to the full license agreement. Can be any string in case of custom licenses.
|-
| media_files || [[#Media Files|Media File]][] || || ✓
| A list of media files, such as screen shots of the mod in action. See [[#Media Files]].
|-
| 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 || Integer || ✓ || ✓
| releases || [[#Releases|Release]][] || ✓* || ✓ || ✓
| Doesn't seem to be implemented yet. Always 0.
| A list of different versions of the mod available for download. See [[#Releases]]. *Only when using <code>namelist</code> [[#/api/mods|parameter]].
|-
|-
| releases || [[#Releases|Release]][] || || ✓
| summary || String || ✓ || ✓ || ✓
| A list of different versions of the mod available for download. See [[#Releases]]
|-
| summary || String || ✓ || ✓
| A shorter mod description.
| A shorter mod description.
|-
|-
| tags || [[#Tags|Tag]][] || ✓ || ✓
| title || String || ✓ || ✓ || ✓
| A list of tag objects that categorize the mod. See [[#Tags]].
|-
| title || String || ✓ || ✓
| The mod's human-readable name.
| The mod's human-readable name.
|-
|-
| updated_at || String(ISO 8601) || ✓ || ✓
| category || [[Mod_details_API#Category|Category]]? || ✓ || ✓ || ✓
| The datetime the mod was last updated, in the full ISO 8601 format, with a space separator instead of 'T'.
| A single category describing the mod. See [[Mod_details_API#Category]].
|-
| visits_count || Integer || ✓ || ✓
| The number of times the mod was viewed, but perhaps only counted on the web interface???
|}
 
=== License Flags ===
 
The "license_flags" is an 11 bit number that describe generally what permissions the mod's license grants.
 
{| class="wikitable"
! 2<sup>n</sup> !! Title !! Description
|-
! colspan=3 | Permissions
|-
|-
| 0 || Commercial Use || This software and derivatives may be used for commercial purposes
| thumbnail || String(relative URL) || || ✓ || ✓
| The relative path to the thumbnail of the mod. For mods that have no thumbnail it may be absent or default to <code>"/assets/.thumb.png"</code>. Prepend "assets-mod.factorio.com".
|-
|-
| 1 || Modification || The software may be modified.
| changelog || String || || || ✓
| A string describing the recent changes to a mod.
|-
| created_at || String(ISO 8601) || || || ✓
| ISO 8601 for when the mod was created.
|-
|-
| 2 || Distribution || You may distribute this software.
| description || String || || || ✓
| A longer description of the mod, in text only format.
|-
|-
| 3 || Patent Use || This license provides an express grant of patent rights from the contributor to the recipient.
| source_url || String || || || ✓
| A URL to the mod's source code.
|-
|-
| 4 || Private Use || You may use and modify the software without distributing it.
| github_path || String || || || ✓
| Deprecated: Use <code>source_url</code> instead. A link to the mod's github project page, just prepend "github.com/". Can be blank ("").
|-
|-
! colspan=3 | Conditions
| homepage || String || || || ✓
| Usually a URL to the mod's main project page, but can be any string.
|-
|-
| 5 || Disclose Source || Source code must be made available when distributing the software.
| tags || [[#Tags|Tag]][] || || || ✓
| A list of tag names that categorize the mod. See [[#Tags]].
|-
|-
| 6 || License & Copyright Notice || Include a copy of the license and copyright notice with the code.
| license || [[#License]][] || || || ✓
| The license that applies to the mod. See [[#License]].
|-
|-
| 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.
|-
| 8 || State Changes || Indicate changes made to the code.
|-
! colspan=3 | Limitations
|-
| 9 || Hold Liable || Software is provided without warranty and the software author/license owner cannot be held liable for damages.
|-
| 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.
|}
|}


=== 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"
{| class="wikitable"
! Key !! Type !! Description
! Key !! Type !! Description
|-
|-
| id || Integer || A numerical ID unique to this tag.
| download_url || String
| Path to download for a mod. starts with "/download" and does not include a full url. See [[#Downloading Mods]]
|-
|-
| name || String || An all lower-case string used to identify this tag internally.
| file_name || String  
| The file name of the release. Always seems to follow the pattern "{name}_{version}.zip"
|-
|-
| title || String || The tag's human-readable tag name.
| 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 8601 for when the mod was released.
|-
|-
| description || String || A short description for the tag.
| version || String  
| The version string of this mod release. Used to determine dependencies.  
|-
|-
| type || String ||  
| sha1 || String  
| The sha1 key for the file
|-
|}
|}
=== Tags ===


Currently, there are only a fixed number of tags available, these include:
Currently, there are only a fixed number of tags available, these include:
Line 237: Line 188:
! id !! type !! name !! title !! description
! id !! type !! name !! title !! description
|-
|-
| 1 || t || general || General || Mods that cannot be sorted into other categories
| 12 || t || transportation || Transportation || Transportation of the player, be it vehicles or teleporters.
|-
| 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.
| 13 || t || logistics || Logistics || Augmented or new ways of transporting materials - belts, inserters, pipes!
|-
|-
| 15 || t || balancing || Balancing || Makes the game much more fair
| ?? || t || combat || Combat || New ways to deal with enemies, be it attack or defense.
|-
|-
| 17 || t || enemies || Enemies || Adds more enemies for more challange
| 17 || t || enemies || Enemies || Changes to enemies or entirely new enemies to deal with.
|-
|-
| 16 || t || weapons || Weapons || Adds more weapons to annihilate the enemy
| 18 || t || armor || Armor || Armors or armor equipment.
|-
|-
| 18 || t || armor || Armor || Armors or armor equipment related.
| ?? || t || environment || Environment || Map generation and terrain modification.
|-
|-
| 19 || t || oil || Oil || Things related to oil related manufacture
| 20 || t || logistic-network || Logistics Network || Related to roboports and logistic robots
|-
|-
| 20 || t || logistics-network || Logistics Network || Related to roboports and logistic robots
| ?? || t || circuit-network || Circuit network || Entities which interact with the circuit network.
|-  
|-  
| 21 || t || storage || Storage || Allows more ways to be able to store items
| 21 || t || storage || Storage || More than just chests.
|-
|-
| 22 || t || power-production || Power Production || Allows more ways to create mass amounts of energy
| 22 || t || power || Power Production || Changes to power production and distribution.
|-
|-
| 23 || t || manufacture || Manufacture || Furnaces, assembling machines, production chains
| 23 || t || manufacturing || Manufacture || Furnaces, assembling machines, production chains
|-
|-
| 24 || t || blueprints || Blueprints ||  
| 24 || t || blueprints || Blueprints || Change blueprint behavior.
|-
|-
| 25 || t || cheats || Cheats || Well, they let you cheat
| 25 || t || cheats || Cheats || Play it your way.
|-  
|-  
| 26 || t || defense || Defense || Mods that add the ability to protect your base more
| 27 || t || mining || Mining || New ores and resources as well as machines.
|-
| 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
| ?? || t || fluids || Fluids || Things related to oil and other fluids.
|-
|-
| 29 || t || trains || Trains || Related to trains
| 29 || t || trains || Trains || Trains are great, but what if they could do even more?
|}
|}


=== Media Files ===
=== License ===
 
A media file object describes a single image, along with a smaller thumbnail sized version of the image.


{| class="wikitable"
{| class="wikitable"
! Key !! Type !! Description
! Key !! Type !! Description
|-
|-
| id || Integer || A numerical ID unique to this media file.
| description || String || A short description of the license.
|-
|-
| width || Integer || Width of the full sized image in pixels.
| id || String || The unique id of the license.
|-
|-
| height || Integer || Height of the full sized image in pixels.
| name || String || The internal name of the license.
|-
|-
| size || Integer || Size of the full image in bytes.
| title || String || The human-readable title of the license.
|-
|-
| urls || [[#Media URLs|Media URL]] || URLs to the full sized image and a thumbnail, see below.
| url || String || Usually a URL to the full license text, but can be any string.
|}
|}


=== Media URLs ===
=== Error ===


{| class="wikitable"
{| class="wikitable"
! Key !! Type !! Description
! Key !! Type !! Description
|-
|-
| original || String(URL) || URL to full sized image.
| message || String ||
|-
| thumb || String(URL) || URL to 128x128px sized thumbnail of 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".
== Downloading Mods ==
 
=== Releases ===
 
{| class="wikitable"
! Key !! Type !! Description
|-
| download_url || String || Path to download for a mod. starts with "/api" and does not include a full url
|-
| downloads_count || Integer || Count of how many times a mod has been downloaded
|-
| factorio_version || String || The version of the game the mod is intended for
|-
| file_name || String || The file name of the release. Always seems to follow the pattern "{name}_{version}.zip"
|-
| file_size || Integer || The size of the file
|-
| game_version || String || The version of the mod (do not confuse with factorio version)
|-
| id || Integer || A numerical ID unique to this release.
|-
| info_json || Object || A copy of the mod's info.json file.
|-
| 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.
|}


=== Error ===
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]].


{| class="wikitable"
Example usage:
! Key !! Type !! Description
https://mods.factorio.com/{download_url}?username={username}&token={token}
|-
| detail || String ||
|}




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

Latest revision as of 09:07, 12 November 2023

Category: Internal API

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 (sent as query parameters):

Key Values Description
hide_deprecated {boolean} Only return non-deprecated mods.
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
sort {enum, one of name, created_at or updated_at} Sort results by this property. Defaults to name when not defined. Ignored for page_size=max queries.
sort_order {enum, one of asc or desc} Sort results ascending or descending. Defaults to descending when not defined. Ignored for page_size=max queries.
namelist {array of strings} Return only mods that match the given names. Either comma-separated names or supply the namelist parameter more than once. Response will include releases instead of latest_release.
version {enum, one of 0.13, 0.14, 0.15, 0.16, 0.17, 0.18, 1.0 or 1.1} Only return non-deprecated mods compatible with this Factorio version


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. Fields may be absent if there is no data.

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. Absent when the namelist parameter is used.
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. *Only when using namelist parameter.
summary String ✓ ✓ ✓ A shorter mod description.
title String ✓ ✓ ✓ The mod's human-readable name.
category Category? ✓ ✓ ✓ A single category describing the mod. See Mod_details_API#Category.
thumbnail String(relative URL) ✓ ✓ The relative path to the thumbnail of the mod. For mods that have no thumbnail it may be absent or default to "/assets/.thumb.png". Prepend "assets-mod.factorio.com".
changelog String ✓ A string describing the recent changes to a mod.
created_at String(ISO 8601) ✓ ISO 8601 for when the mod was created.
description String ✓ A longer description of the mod, in text only format.
source_url String ✓ A URL to the mod's source code.
github_path String ✓ Deprecated: Use source_url instead. 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.
tags Tag[] ✓ A list of tag names that categorize the mod. See #Tags.
license #License[] ✓ The license that applies to the mod. See #License.

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 8601 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

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

id type name title description
12 t transportation Transportation Transportation of the player, be it vehicles or teleporters.
13 t logistics Logistics Augmented or new ways of transporting materials - belts, inserters, pipes!
?? t combat Combat New ways to deal with enemies, be it attack or defense.
17 t enemies Enemies Changes to enemies or entirely new enemies to deal with.
18 t armor Armor Armors or armor equipment.
?? t environment Environment Map generation and terrain modification.
20 t logistic-network Logistics Network Related to roboports and logistic robots
?? t circuit-network Circuit network Entities which interact with the circuit network.
21 t storage Storage More than just chests.
22 t power Power Production Changes to power production and distribution.
23 t manufacturing Manufacture Furnaces, assembling machines, production chains
24 t blueprints Blueprints Change blueprint behavior.
25 t cheats Cheats Play it your way.
27 t mining Mining New ores and resources as well as machines.
?? t fluids Fluids Things related to oil and other fluids.
29 t trains Trains Trains are great, but what if they could do even more?

License

Key Type Description
description String A short description of the license.
id String The unique id of the license.
name String The internal name of the license.
title String The human-readable title of the license.
url String Usually a URL to the full license text, but can be any string.

Error

Key Type Description
message 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}

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