External Tools
This page is directed to developers of external tools, who are interested in accessing the data from the APIs of the Factorio Item Browser.
The data of the Factorio Item Browser is actually split between two separate APIs: The Combination API holding information of combinations on a meta level, and the Data API holding the actual information about items, recipes etc.
- Base URL: https://combination-api.factorio-item-browser.com/
- API Specification: https://docs.factorio-item-browser.com/combination-api/
The Combination API manages the metadata of combinations, whether their data is available in the Data API, their export status, and so on.
A "Combination" is a list of mods, which the player is using for their game. While the list of mod names already identifies a combination, the API introduces Combination IDs for easier management of the combinations across the different components of the FIB.
Most of the data of the Combination API is provided by its consumers: Combinations are created as they get requested through their mod names, and export status get updated by the several components of the FIB. An exception to this is validating a combination, i.e. checking whether the contained mods are compatible to each other and the latest version of Factorio. For this, the Combination API accesses the Factorio Mod Portal to fetch the data of mods and their releases.
- Base URL: https://data-api.factorio-item-browser.com/
- API Specification: https://docs.factorio-item-browser.com/data-api/
The Data API, or historically only the "API" as it was the first one to be built, is the most complex API, because it holds all the data of the items, recipes etc.
The data source for the Data API is (indirectly) the Factorio game itself, using the mods from the Factorio Mod Portal and dumping the required data to a database through a fully automated process.
Both APIs require an API Key to be allowed to access any data of it. If you are interested in the APIs and their data, contact me (BluePsyduck#8206) in my Discord Server and I will be happy to provide you the keys.
One exception is the Data API and using the combination id 2f4a45fa-a509-a9d1-aae6-ffcf984a7a76 representing the
vanilla game: The data of this combination is not locked behind an API key, if you first want to take a look on the
actual data.
At this point, I want to give some examples of accessing the APIs and what data to expect. This should hopefully make clear of how the APIs work. If anything is not clear, feel free to ask me on my discord server.
For the example, we are taking the combination consisting of the base mod, and Krastorio2.
A first step in most cases is to "convert" the list of mods to the Combination ID required for the Data API. If the Combination ID is already known, then this step can be skipped.
To get the Combination ID, send the according request to the Combination API:
GET /status HTTP/2
Host: combination-api.factorio-item-browser.com
Mod-Names: base,Krastorio2
Api-Key: abcThis request will yield the following response:
{
"id": "b5775459-78a6-d8bb-d175-ad8a210ba378",
"shortId": "5wq8Z34w6Jpqorl6j0prxS",
"modNames": [
"Krastorio2",
"base"
]
}You see the id, which is the full Combination ID required by the Data API. as well as the shortId, which is used
by the Factorio Item Browser website in the URL.
The response also contains information about whether data is available in the Data API. This information is considered deprecated, and will be removed in the future, so don't use this anymore. Instead, see example #2 to get the status of the combination.
When the Combination ID is known, you can request the status of the Combination from the Data API, telling you whether data is actually available.
GET /b5775459-78a6-d8bb-d175-ad8a210ba378 HTTP/2
Host: data-api.factorio-item-browser.com
Api-Key: abcThis request will yield the following response:
{
"dataVersion": 1,
"importTime": "2021-12-24T14:07:22+01:00"
}The response contains a timestamp of when the data was (last) imported into the database, which gives you a rough
estimate of how old the data is. The dataVersion specifies, which version of data is available, currently always 1,
but new data will be added soon.
If data is not available, the server will answer with a status code 404 instead. Note that all endpoints will actually return with 404 on unavailable combinations, but some endpoints may also return a 404 in other circumstances (like unknown recipes).
With knowing the id of our combination, and that the data is actually available, we can now send requests to the Data API.
As an example, we request all recipes which have a electronic-circuit as a product, i.e. all recipes with which we can
create that item.
POST /b5775459-78a6-d8bb-d175-ad8a210ba378/item/product HTTP/2
Host: data-api.factorio-item-browser.com
Api-Key: abc
Accept-Language: en
Content-Type: application/json
{
"type": "item",
"name": "electronic-circuit",
"numberOfResults": 10,
"indexOfFirstResult": 0
}As you can see, the combination id is part of the request URL, so that the Data API knows of which combination you want the data from.
Part of the header is also the Accept-Language: The data API supports all languages from Factorio, as long as the mods
provide the translations for their items and recipes. Changing the language will result in the properties label and
description in the response to be translated accordingly.
The request will result in the following response:
{
"item": {
"type": "item",
"name": "electronic-circuit",
"label": "Electronic circuit",
"description": "",
"recipes": [
{
"name": "electronic-circuit",
"label": "Electronic circuit",
"description": "",
"mode": "normal",
"ingredients": [
{
"type": "item",
"name": "wood",
"label": "Wood",
"description": "",
"amount": 1.0
},
{
"type": "item",
"name": "iron-plate",
"label": "Iron plate",
"description": "",
"amount": 1.0
},
{
"type": "item",
"name": "copper-cable",
"label": "Copper cable",
"description": "Can also be used to manually connect and disconnect electric poles and power switches with [Build].",
"amount": 4.0
}
],
"products": [
{
"type": "item",
"name": "electronic-circuit",
"label": "Electronic circuit",
"description": "",
"amount": 2.0
}
],
"craftingTime": 2.0,
"expensiveVersion": {
"name": "electronic-circuit",
"label": "Electronic circuit",
"description": "",
"mode": "expensive",
"ingredients": [
{
"type": "item",
"name": "wood",
"label": "Wood",
"description": "",
"amount": 1.0
},
{
"type": "item",
"name": "iron-plate",
"label": "Iron plate",
"description": "",
"amount": 1.0
},
{
"type": "item",
"name": "copper-cable",
"label": "Copper cable",
"description": "Can also be used to manually connect and disconnect electric poles and power switches with [Build].",
"amount": 4.0
}
],
"products": [
{
"type": "item",
"name": "electronic-circuit",
"label": "Electronic circuit",
"description": "",
"amount": 1.0
}
],
"craftingTime": 2.0
}
}
],
"totalNumberOfRecipes": 1
}
}The essential data is below the recipes key: Here you find the one recipe producing an electronic circuit, together
with its expensive variant. The Data API will always return both variants (if available) in this format whenever a
recipe is returned.
But which machines can actually produce the recipe from example #2? Let's find it out :D
POST /b5775459-78a6-d8bb-d175-ad8a210ba378/recipe/machines HTTP/2
Host: data-api.factorio-item-browser.com
Api-Key: abc
Accept-Language: en
Content-Type: application/json
{
"name": "electronic-circuit",
"numberOfResults": 10,
"indexOfFirstResult": 0
}When sending this request, we will receive the following response:
{
"machines": [
{
"name": "character",
"label": "Character",
"description": "",
"craftingSpeed": 1.0,
"numberOfItemSlots": 255,
"numberOfFluidInputSlots": 0,
"numberOfFluidOutputSlots": 0,
"numberOfModuleSlots": 0,
"energyUsage": 0.0,
"energyUsageUnit": "W"
},
{
"name": "assembling-machine-1",
"label": "Assembling machine 1",
"description": "",
"craftingSpeed": 0.5,
"numberOfItemSlots": 255,
"numberOfFluidInputSlots": 0,
"numberOfFluidOutputSlots": 0,
"numberOfModuleSlots": 0,
"energyUsage": 75.0,
"energyUsageUnit": "kW"
},
{
"name": "assembling-machine-2",
"label": "Assembling machine 2",
"description": "",
"craftingSpeed": 0.75,
"numberOfItemSlots": 255,
"numberOfFluidInputSlots": 1,
"numberOfFluidOutputSlots": 1,
"numberOfModuleSlots": 2,
"energyUsage": 125.0,
"energyUsageUnit": "kW"
},
{
"name": "assembling-machine-3",
"label": "Assembling machine 3",
"description": "",
"craftingSpeed": 1.25,
"numberOfItemSlots": 255,
"numberOfFluidInputSlots": 1,
"numberOfFluidOutputSlots": 1,
"numberOfModuleSlots": 4,
"energyUsage": 200.0,
"energyUsageUnit": "kW"
},
{
"name": "kr-advanced-assembling-machine",
"label": "Advanced assembling machine",
"description": "",
"craftingSpeed": 5.0,
"numberOfItemSlots": 8,
"numberOfFluidInputSlots": 1,
"numberOfFluidOutputSlots": 1,
"numberOfModuleSlots": 4,
"energyUsage": 925.0,
"energyUsageUnit": "kW"
}
],
"totalNumberOfResults": 5
}Here we see that a total of 5 machines can produce the recipe electronic-circuit. One of the machines is actually the
character entity, meaning that this recipe can be crafted in-hand without any machines at all. If the recipe is
hand-craftable, the "Character" machine will always return as first result.
