Mod portal API: Difference between revisions

From Official Factorio Wiki
Jump to navigation Jump to search
← Older edit
Updating some stuff
Sevens7 (talk | contribs)
11 edits
→Result Entry: latest_release does not appear as a Release object in the search api response
 
(57 intermediate revisions by 16 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>
List of bookmarked mods can be accessed from following URL (requires authentication).
<code>https://mods.factorio.com/api/bookmarks?username={username}&token={token}</code>
You can also toggle a bookmark using following URL, with <code>state</code> being <code>on</code> or <code>off</code>.
<code>https://mods.factorio.com/api/bookmarks/toggle?username={username}&token={token}&mod={name}&state={state}</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.
| <code>hide_deprecated</code> || Boolean? || Whether to exclude incompatible mods from the results. Defaults to true if absent
|-
|-
| owner ||||
| <code>page</code> || Integer? || Page number to fetch, ignored for <code>page_size="max"</code> queries. Defaults to 1 when absent
|-
|-
| 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
| <code>page_size</code> || (Integer <nowiki>&#124;</nowiki> <code>"max"</code>)? || The amount of results to show per page, or all results when passed <code>"max"</code>. Defaults to 25 when absent
|-
|-
| page_size ||{an integer}||The amount of results to show in your search
| <code>sort</code> || String? (one of <code>"name"</code>, <code>"created_at"</code> or <code>"updated_at"</code>) || Sort results by this property. Defaults to <code>"name"</code> when absent. Ignored for <code>page_size=max</code> queries
|-
|-
| q ||{a string}||Name/Partial Name of mod you want to search for
| <code>sort_order</code> || String? (either <code>"asc"</code> or <code>"desc"</code>) || Sort results ascending or descending. Defaults to <code>"desc"</code> when absent. Ignored for <code>page_size="max"</code> queries
|-
|-
| tags ||||
| <code>namelist</code> || String[]? || Return only mods that match the given names. Response will include <code>releases</code> instead of <code>latest_release</code>
|-
| <code>version</code> || Factorio Version String (e.g. <code>"2.0.76"</code>) || Mods incompatible with this Factorio version are marked as deprecated and hidden for <code>hide_deprecated=true</code> queries.
|}
|}


Line 38: Line 50:
=== /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
|-
| 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 ===
Returns more information of a mod.


== JSON Object Types ==
See [[#Result Entry]], "Full" column.


=== Mod List Response ===
=== /api/bookmarks ===


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


=== Pagination ===
=== /api/search ===
POST Parameters (sent as json content):


{| class="wikitable"
{| class="wikitable"
! Key !! Type !! Description
! Keys !! Values !! Descrption
|-
| 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.
| <code>version</code> || Factorio Version String (e.g. <code>"2.0.76"</code>) || The version of Factorio to search mods for, mods incompatible with this version are marked as "deprecated"
|-
|-
| page || Integer || The current page number.
| <code>lang</code> || Locale Identifier? || No effect on response
|-
|-
| page_count || Integer || The total number of pages returned.
| <code>is_space_age</code> || Boolean? || No effect on response
|-
|-
| page_size || Integer || The number of results per page.
| <code>username</code> || String || factorio.com account username to use for the query
|}
 
=== 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.
| <code>token</code> || String || factorio.com account token to use for the query
|-
| 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 "Short" column, and those returned the the api/mods/{name} endpoint are marked with a check in the "Full" column.
 
{| 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
|-
| 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) || || ✓
| A longer description of the mod, with HTML tags.
|-
| downloads_count || Integer || ✓ || ✓
| Number of downloads.
|-
| first_media_file || [[#Media Files|Media File]] || ✓ ||
| The first media file in the "media_files" list.
|-
| game_versions || 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 || ✓ || ✓
| <code>query</code> || String? || The string to filter by, empty or absent does not filter
| Usually a URL to the mod's main project page, but can be any string.
|-
|-
| id || Integer || ✓ || ✓
| <code>sort_attribute</code> || [[#Sort Attribute|Sort Attribute]]? || The attribute to sort the results by. Defaults to <code>"relevancy"</code> if absent
| A numerical mod ID used to identify the mod in other API endpoints.
|-
|-
| latest_release || [[#Releases|Release]] || ✓ ||
| <code>only_bookmarks</code> || Boolean? || Whether to filter results down to only mods bookmarked by the account given by <code>username</code> and <code>token</code>. Defaults to false if absent
| The latest version of the mod available for download. See [[#Releases]]
|-
|-
| license_flags || Integer(11 bit) || ✓ || ✓
| <code>show_deprecated</code> || Boolean? || Whether to show mods incompatible with the Factorio version specified with <code>version</code>. Defaults to false if absent
| A bit field describing what permissions the mod's license grants. See [[#License Flags]]
|-
|-
| license_name || String || ✓ || ✓
| <code>highlight_pre_tag</code> || String? || A string to place in front of the matched text for <code>query</code>, defaults to <code>"&lt;em&gt;"</code> if absent. If <code>query</code> is empty or absent, value is ignored
| The mod's license name.
|-
|-
| license_url || String || ✓ || ✓
| <code>highlight_post_tag</code> || String? || A string to place behind the matched text for <code>query</code>, defaults to <code>"&lt;/em&gt;"</code> if absent. If <code>query</code> is empty or absent, value is ignored
| A URL link to the full license agreement. Can be any string in case of custom licenses.
|-
|-
| media_files || [[#Media Files|Media File]][] || || ✓
| <code>expansion</code> || String[]? || A whitelist of expansion(s) to filter mods with (currently the only valid value is <code>"space-age"</code>)
| A list of media files, such as screen shots of the mod in action. See [[#Media Files]].
|-
|-
| name || String || ✓ || ✓
| <code>exclude_expansion</code> || String[]? || A blacklist of expansion(s) to filter mods with (currently the only valid value is <code>"space-age"</code>)
| The mod's machine-readable ID string.
|-
|-
| owner || String || ✓ || ✓
| <code>category</code> || [[Mod_details_API#Category|Category]][]? || A whitelist of categories to filter mods with
| The Factorio username of the mod's author.
|-
|-
| ratings_count || Integer || ✓ || ✓
| <code>exclude_category</code> || [[Mod_details_API#Category|Category]][]? || A blacklist of categories to filter mods with
| Doesn't seem to be implemented yet. Always 0.
|-
|-
| releases || [[#Releases|Release]][] || || ✓
| <code>tag</code> || [[Mod_details_API#Tags|Tag]][]? || A whitelist of tags to filter mods with
| A list of different versions of the mod available for download. See [[#Releases]]
|-
|-
| summary || String || ✓ || ✓
| <code>exclude_tag</code> || [[Mod_details_API#Tags|Tag]][]? || A blacklist of tags to filter mods with
| A shorter mod description.
|-
|-
| tags || [[#Tags|Tag]][] || ✓ || ✓
| <code>page</code> || Integer || Page number you would like to show, ignored for <code>page_size="max"</code> queries
| A list of tag objects that categorize the mod. See [[#Tags]].
|-
|-
| title || String || ✓ || ✓
| <code>page_size</code> || Integer or <code>"max"</code> ||The amount of results to show per page, or all results when passed <code>"max"</code>
| The mod's human-readable name.
|-
| updated_at || String(ISO 8601) || ✓ || ✓
| The datetime the mod was last updated, in the full ISO 8601 format, with a space separator instead of 'T'.
|-
| visits_count || Integer || ✓ || ✓
| The number of times the mod was viewed, but perhaps only counted on the web interface???
|}
|}


=== License Flags ===
== JSON Object Types ==


The "license_flags" is an 11 bit number that describe generally what permissions the mod's license grants.
=== Sort Attribute ===


{| class="wikitable"
{| class="wikitable"
! 2<sup>n</sup> !! Title !! Description
|-
|-
! colspan=3 | Permissions
! Attribute !! Sort By
|-
|-
| 0 || Commercial Use || This software and derivatives may be used for commercial purposes
| <code>"relevancy"</code> || Seemingly identical to <code>"last_updated_at"</code>
|-
|-
| 1 || Modification || The software may be modified.
| <code>"most_downloads"</code> || Download count
|-
|-
| 2 || Distribution || You may distribute this software.
| <code>"last_updated_at"</code> || Most recently updated
|-
|-
| 3 || Patent Use || This license provides an express grant of patent rights from the contributor to the recipient.
| <code>"trending"</code> || Internal metric
|}
 
=== Mod List Response ===
 
{| class="wikitable"
! Key !! Type !! Description
|-
|-
| 4 || Private Use || You may use and modify the software without distributing it.
| <code>pagination</code> || [[#Pagination|Pagination]] || See [[#Pagination]]
|-
|-
! colspan=3 | Conditions
| <code>results</code> || [[#Result Entry|Result]][] || A list of mods, matching the filters specified by the query
|-
|}
| 5 || Disclose Source || Source code must be made available when distributing the software.
 
|-
=== Pagination ===
| 6 || License & Copyright Notice || Include a copy of the license and copyright notice with the code.
 
{| class="wikitable"
! Key !! Type !! Description
|-
|-
| 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.
| <code>count</code> || Integer || Total number of mods that match your specified filters.
|-
|-
| 8 || State Changes || Indicate changes made to the code.
| <code>links</code> || [[#Pagination_Links|Links]]? || Utility links to mod portal api requests, preserving all filters and search queries. Absent from the <code>/api/search</code> endpoint response
|-
|-
! colspan=3 | Limitations
| <code>page</code> || Integer || The current page number.
|-
|-
| 9 || Hold Liable || Software is provided without warranty and the software author/license owner cannot be held liable for damages.
| <code>page_count</code> || Integer || The total number of pages returned.
|-
|-
| 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.
| <code>page_size</code> || Integer || The number of results per page.
|}
|}


=== Tags ===
=== Pagination Links ===


{| class="wikitable"
{| class="wikitable"
! Key !! Type !! Description
! Key !! Type !! Description
|-
|-
| id || Integer || A numerical ID unique to this tag.
| <code>first</code> || String(URL) || URL to the first page of the results, or <code>null</code> if you're already on the first page
|-
| <code>prev</code> || String(URL) || URL to the previous page of the results, or <code>null</code> if you're already on the first page
|-
|-
| name || String || An all lower-case string used to identify this tag internally.
| <code>next</code> || String(URL) || URL to the next page of the results, or <code>null</code> if you're already on the last page
|-
|-
| title || String || The tag's human-readable tag name.
| <code>last</code> || String(URL) || URL to the last page of the results, or <code>null</code> if you're already on the last page
|-
| description || String || A short description for the tag.
|-
| type || String ||
|}
|}


Currently, there are only a fixed number of tags available, these include:
=== 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.


{| class="wikitable"
{| class="wikitable"
! id !! type !! name !! title !! 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 !!+ style='writing-mode:vertical-lr;vertical-align:bottom;font-size:90%' | api/search !! Description
|-
| <code>latest_release</code> || [[#Releases|Release]]? || ✓* || || ||
| The latest version of the mod available for download. <b>*Absent when the <code>namelist</code> [[#/api/mods|parameter]] is used</b>.
|-
|-
| 1 || t || general || General || Mods that cannot be sorted into other categories
| <code>downloads_count</code> || Integer || ✓ || ✓ || ✓ || ✓
| Number of downloads.
|-
|-
| 2 || t || non-game-changing || Non-Game-Changing || Changes only look&feel. New graphics, new sounds, ... such things.
| <code>name</code> || String || ✓ || ✓ || ✓ || ✓
| The mod's machine-readable ID string.
|-
|-
| 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...
| <code>owner</code> || String || ✓ || ✓ || ✓ || ✓
| The Factorio username of the mod's author.
|-
|-
| 6 || t || big-mods || Big Mods || Too big and/or changes too much of the game to be fit anywhere else
| <code>releases</code> || [[#Releases|Release]][] || ✓* || ✓ || ✓ ||
| A list of different versions of the mod available for download. See [[#Releases]]. <b>*Only when using <code>namelist</code> [[#/api/mods|parameter]]</b>.
|-
|-
| 12 || t || transportation || Transportation || Player transport
| <code>summary</code> || String || ✓ || ✓ || ✓ || ✓
| A shorter mod description.
|-
| <code>title</code> || String || ✓ || ✓ || ✓ || ✓
| The mod's human-readable name.
|-
|-
| 13 || t || logistics || Logistics || Transport of materials
| <code>category</code> || [[Mod_details_API#Category|Category]]? || ✓ || ✓ || ✓ || ✓
| A single category describing the mod. See [[Mod_details_API#Category]].
 
|-
|-
| 14 || t || utility || Utility || Helps with certain things the player is doing.
| <code>score</code> || Integer || ✓ || ✓* || ✓* ||
| The score of the mod. <b>*Only when not 0</b>.
|-
|-
| 15 || t || balancing || Balancing ||
| <code>thumbnail</code> || 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".
|-
|-
| 17 || t || enemies || Enemies ||
| <code>changelog</code> || String? || || || ✓ ||
| A string describing the recent changes to a mod.
|-
| <code>created_at</code> || String(ISO 8601) || || || ✓ || ✓
| ISO 8601 for when the mod was created. (RFC 3339 nano)
|-
|-
| 16 || t || weapons || Weapons ||
| <code>updated_at</code> || String(ISO 8601) || || || ✓ || ✓
| ISO 8601 for when the mod was last updated. (RFC 3339 nano)
|-
|-
| 18 || t || armor || Armor || Armors or armor equipment related.
| <code>last_highlighted_at</code> || String(ISO 8601)? || || || ✓ ||
| ISO 8601 for when the mod was last featured on the "Highlighted mods" tab. (RFC 3339 nano)
|-
|-
| 19 || t || oil || Oil || Things related to oil related manufacture
| <code>description</code> || String? || || || ✓ ||
| A longer description of the mod, in text only format.
|-
|-
| 20 || t || logistics-network || Logistics Network || Related to roboports and logistic robots
| <code>source_url</code> || String? || || || ✓ || ✓
|-
| A URL to the mod's source code.
| 21 || t || storage || Storage ||
|-
|-
| 22 || t || power-production || Power Production ||
| <code>github_path</code> || String? || || || ✓ ||
| Deprecated: Use <code>source_url</code> instead. A link to the mod's github project page, just prepend "github.com/". Can be blank ("").
|-
|-
| 23 || t || manufacture || Manufacture || Furnaces, assembling machines, production chains
| <code>homepage</code> || String || || || ✓ ||
| Usually a URL to the mod's main project page, but can be any string.
|-
|-
| 24 || t || blueprints || Blueprints ||
| <code>tags</code> || [[Mod_details_API#Tags|Tag]][] || || || ✓ || ✓
| A list of tag names that categorize the mod. See [[#Mod_details_API#Tags]].
|-
|-
| 25 || t || cheats || Cheats ||
| <code>license</code> || [[#License]][] || || || ✓ ||
|-
| The license that applies to the mod. See [[#License]].
| 26 || t || defense || Defense ||
|-
|-
| 27 || t || mining || Mining ||
| <code>deprecated</code> || Boolean || || || ✓ || ✓
| True if the mod is marked as deprecated by its owner.
|-
|-
| 28 || t || info || Info || Mods that provide additional information to the player
| <code>requires_space_age</code> || Boolean || ? || ? || ? || ✓
| True if the mod depends on the user having the Space Age expansion.
|-
|-
| 29 || t || trains || Trains ||  
| <code>highlighted_fields</code> || Object{"name", "owner", "summary", "title"} || || || || ✓
| The fields that <code>query</code> field matched against, the matching text surrounded by the text specified with the <code>highlight_*_tag</code> parameters.
|}
|}


=== Media Files ===
=== Releases ===


A media file object describes a single image, along with a smaller thumbnail sized version of the image.
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 media file.
| <code>download_url</code> || String
| Path to download for a mod. starts with "/download" and does not include a full url. See [[#Downloading Mods]]
|-
|-
| width || Integer || Width of the full sized image in pixels.
| <code>file_name</code> || String
| The file name of the release. Always seems to follow the pattern "{name}_{version}.zip"
|-
|-
| height || Integer || Height of the full sized image in pixels.
| <code>info_json</code> || 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
|-
| <code>released_at</code> || String(ISO 8601)
| ISO 8601 for when the mod was released. (RFC 3339 nano)
|-
|-
| size || Integer || Size of the full image in bytes.
| <code>version</code> || String
| The version string of this mod release. Used to determine dependencies.  
|-
|-
| urls || [[#Media URLs|Media URL]] || URLs to the full sized image and a thumbnail, see below.
| <code>sha1</code> || String
|}
| The sha1 key for the file.
 
|-  
=== Media URLs ===
| <code>feature_flags</code> || String[]?
 
| The feature flags this mod uses. See [https://lua-api.factorio.com/latest/types/FeatureFlags.html FeatureFlags]
{| class="wikitable"
|-  
! Key !! Type !! Description
|-
| original || String(URL) || URL to full sized image.
|-
| 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".
=== License ===
 
=== Releases ===


{| class="wikitable"
{| class="wikitable"
! Key !! Type !! Description
! Key !! Type !! Description
|-
|-
| download_url || String ||
| <code>description</code> || String || A short description of the license.
|-
| downloads_count || Integer ||
|-
| factorio_version || String ||
|-
| file_name || String || The file name of the release. Always seems to follow the pattern "{name}_{version}.zip"
|-
| file_size || Integer ||
|-
|-
| game_version || String ||
| <code>id</code> || String || The unique id of the license. For more information on each, see [[#Mod_details_API#License|License]]
|-
|-
| id || Integer || A numerical ID unique to this release.
| <code>name</code> || String || The internal name of the license.
|-
|-
| info_json || Object || A copy of the mod's info.json file.
| <code>title</code> || String || The human-readable title of the license.
|-
| released_at || String(ISO 8601) ||
|-
|-
| version || String || The version string of this mod release. Used to determine dependencies.  
| <code>url</code> || String || Usually a URL to the full license text, but can be any string.
|}
|}


Line 339: Line 293:


{| class="wikitable"
{| class="wikitable"
! Key !! Type !! Description
! Key !! Type
|-
|-
| detail || String ||
| <code>message</code> || 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:
<code>https://mods.factorio.com/{download_url}?username={username}&token={token}</code>




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

Latest revision as of 18:44, 28 July 2026

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

List of bookmarked mods can be accessed from following URL (requires authentication).

https://mods.factorio.com/api/bookmarks?username={username}&token={token}

You can also toggle a bookmark using following URL, with state being on or off.

https://mods.factorio.com/api/bookmarks/toggle?username={username}&token={token}&mod={name}&state={state}

Endpoints

/api/mods

GET Parameters (sent as query parameters):

Key Values Description
hide_deprecated Boolean? Whether to exclude incompatible mods from the results. Defaults to true if absent
page Integer? Page number to fetch, ignored for page_size="max" queries. Defaults to 1 when absent
page_size (Integer | "max")? The amount of results to show per page, or all results when passed "max". Defaults to 25 when absent
sort String? (one of "name", "created_at" or "updated_at") Sort results by this property. Defaults to "name" when absent. Ignored for page_size=max queries
sort_order String? (either "asc" or "desc") Sort results ascending or descending. Defaults to "desc" when absent. Ignored for page_size="max" queries
namelist String[]? Return only mods that match the given names. Response will include releases instead of latest_release
version Factorio Version String (e.g. "2.0.76") Mods incompatible with this Factorio version are marked as deprecated and hidden for hide_deprecated=true queries.


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.

/api/bookmarks

Returns array of mod names

/api/search

POST Parameters (sent as json content):

Keys Values Descrption
version Factorio Version String (e.g. "2.0.76") The version of Factorio to search mods for, mods incompatible with this version are marked as "deprecated"
lang Locale Identifier? No effect on response
is_space_age Boolean? No effect on response
username String factorio.com account username to use for the query
token String factorio.com account token to use for the query
query String? The string to filter by, empty or absent does not filter
sort_attribute Sort Attribute? The attribute to sort the results by. Defaults to "relevancy" if absent
only_bookmarks Boolean? Whether to filter results down to only mods bookmarked by the account given by username and token. Defaults to false if absent
show_deprecated Boolean? Whether to show mods incompatible with the Factorio version specified with version. Defaults to false if absent
highlight_pre_tag String? A string to place in front of the matched text for query, defaults to "<em>" if absent. If query is empty or absent, value is ignored
highlight_post_tag String? A string to place behind the matched text for query, defaults to "</em>" if absent. If query is empty or absent, value is ignored
expansion String[]? A whitelist of expansion(s) to filter mods with (currently the only valid value is "space-age")
exclude_expansion String[]? A blacklist of expansion(s) to filter mods with (currently the only valid value is "space-age")
category Category[]? A whitelist of categories to filter mods with
exclude_category Category[]? A blacklist of categories to filter mods with
tag Tag[]? A whitelist of tags to filter mods with
exclude_tag Tag[]? A blacklist of tags to filter mods with
page Integer Page number you would like to show, ignored for page_size="max" queries
page_size Integer or "max" The amount of results to show per page, or all results when passed "max"

JSON Object Types

Sort Attribute

Attribute Sort By
"relevancy" Seemingly identical to "last_updated_at"
"most_downloads" Download count
"last_updated_at" Most recently updated
"trending" Internal metric

Mod List Response

Key Type Description
pagination Pagination See #Pagination
results Result[] A list of mods, matching the filters specified by the query

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. Absent from the /api/search endpoint response
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 api/search Description
latest_release Release? ✓* The latest version of the mod available for download. *Absent when the namelist parameter is used.
downloads_count Integer ✓ ✓ ✓ ✓ Number of downloads.
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.
score Integer ✓ ✓* ✓* The score of the mod. *Only when not 0.
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. (RFC 3339 nano)
updated_at String(ISO 8601) ✓ ✓ ISO 8601 for when the mod was last updated. (RFC 3339 nano)
last_highlighted_at String(ISO 8601)? ✓ ISO 8601 for when the mod was last featured on the "Highlighted mods" tab. (RFC 3339 nano)
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 #Mod_details_API#Tags.
license #License[] ✓ The license that applies to the mod. See #License.
deprecated Boolean ✓ ✓ True if the mod is marked as deprecated by its owner.
requires_space_age Boolean ? ? ? ✓ True if the mod depends on the user having the Space Age expansion.
highlighted_fields Object{"name", "owner", "summary", "title"} ✓ The fields that query field matched against, the matching text surrounded by the text specified with the highlight_*_tag parameters.

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. (RFC 3339 nano)
version String The version string of this mod release. Used to determine dependencies.
sha1 String The sha1 key for the file.
feature_flags String[]? The feature flags this mod uses. See FeatureFlags

License

Key Type Description
description String A short description of the license.
id String The unique id of the license. For more information on each, see 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
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=219384"