Mod portal API: Difference between revisions
No edit summary |
(→/api/mods: add 2.0 version filter) |
||
(73 intermediate revisions by 15 users not shown) | |||
Line 1: | Line 1: | ||
<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 7: | Line 9: | ||
<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 == | |||
=== /api/mods === | |||
GET Parameters (sent as query parameters): | |||
{| class="wikitable" | {| class="wikitable" | ||
! Key !! | ! 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 | ||
| The | |||
|- | |- | ||
| | | 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. | ||
|- | |- | ||
| | | 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. | ||
| | |- | ||
| 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>. | |||
|- | |||
| version || {enum, one of 0.13, 0.14, 0.15, 0.16, 0.17, 0.18, 1.0, 1.1 or 2.0} || 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 === | |||
{| 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. Fields may be absent if there is no data. | |||
{| 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 | |||
|- | |- | ||
| | | latest_release || [[#Releases|Release]]? || ✓ || || | ||
| | | The latest version of the mod available for download. Absent when the <code>namelist</code> [[#/api/mods|parameter]] is used. | ||
|- | |- | ||
| | | downloads_count || Integer || ✓ || ✓ || ✓ | ||
| | | Number of downloads. | ||
|- | |- | ||
| 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. | ||
|- | |- | ||
| | | releases || [[#Releases|Release]][] || ✓* || ✓ || ✓ | ||
| | | A list of different versions of the mod available for download. See [[#Releases]]. *Only when using <code>namelist</code> [[#/api/mods|parameter]]. | ||
|- | |||
| summary || String || ✓ || ✓ || ✓ | |||
| A shorter mod description. | |||
|- | |||
| title || String || ✓ || ✓ || ✓ | |||
| The mod's human-readable name. | |||
|- | |||
| category || [[Mod_details_API#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 <code>"/assets/.thumb.png"</code>. 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 <code>source_url</code> 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 || [[#Tags|Tag]][] || || || ✓ | |||
| A list of tag names that categorize the mod. See [[#Tags]]. | |||
|- | |||
| license || [[#License]][] || || || ✓ | |||
| The license that applies to the mod. See [[#License]]. | |||
|- | |||
| deprecated || Boolean? || || || ✓ | |||
| <ref></ref>True if the mod is marked as deprecated by its owner. Absent when false. | |||
|- | |- | ||
| | |} | ||
=== 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 8601 for when the mod was released. | |||
|- | |- | ||
| | | version || String | ||
| The | | The version string of this mod release. Used to determine dependencies. | ||
|- | |- | ||
| | | sha1 || String | ||
| The | | The sha1 key for the file | ||
|- | |||
|} | |} | ||
=== | === Tags === | ||
Currently, there are only a fixed number of tags available, these include: | |||
{| class="wikitable" | {| class="wikitable" | ||
! | ! 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 === | |||
{| class="wikitable" | |||
! 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 === | |||
{| class="wikitable" | |||
! 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 | Web Authentication API]]. | |||
Example usage: | |||
https://mods.factorio.com/{download_url}?username={username}&token={token} | |||
[[Category:Technical]] |
Latest revision as of 19:13, 19 November 2024
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, 1.1 or 2.0} | 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 |
---|---|---|---|---|---|
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. | ||
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. | ||
deprecated | Boolean? | ✓ | <ref></ref>True if the mod is marked as deprecated by its owner. Absent when false. |
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}