Satisfactory Map Repository - Help

The SMR API is designed to be simple to use. Calls are made using either application/x-www-form-urlencoded or multipart/form-data The method can be freely chosen as long as no file is uploaded. In that case, the latter is required

The API is Stateless

The entire API is designed to resist issues like intermittent connections. It's ok to issue the exact same call again if the connection was interrupted. API calls are atomic in nature; No single operation requires multiple API calls.

Reference implementation

If you prefer reading code over documentation you can find a working reference implementation here. It implements all API functions and also shows how to properly get a users token without ever passing the username or password through your application.

Browser Usage

The API uses browser compatible types on purpose. The content-type for requests are the two that are used for regular forms. The response is given in XML, which the XMLHttpRequest object automatically parses into a tree structure for you so that you can use DOM methods like querySelector on.
We set the Access-Control-Allow-Origin header too, to allow you to use this in your website purely client side in JavaScript.
A very crude API client to get you started can be found in API.js

Caching

Some API calls might send caching headers. We recommend you adhere to them to preserve bandwidth of the user. This is done automatically if you use our API from a web browser.

API Key

All API requests need an API key. You can find this key in your account page. The special "nullguid" 00000000-0000-0000-0000-000000000000 can be used to make anonymous requests.

Make sure to not publish your API key. If you write an application that you plan to publish, direct users to the account page so they can copy their own key or check the chapter below on how to automatically obtain the key. If you publish your key you grant them access to your own account.
If you happen to accidentally publish your key (for example via an accidental git commit), change it immediately in your account.

Getting a Users API Key

To obtain the API key from a user, head over to the remote authentication page.

General API Call Format

Fields depend on the mode. The only required field that is identical for all modes is key=00000000-0000-0000-0000-000000000000.
The mode parameter is appended to the URL. Example: Using the test function is done using /satisfactory/maps/api/test as URL.

General API Answer

The Answer is an XML document. The root element is always <api>. Following child nodes are always present:

  • success: Value is either true or false. If false, the msg node contains failure reason. If true, the data node contains the response.
  • mode: This is your selected mode
  • time: Current system time.
See the individual mode help pages for details on the <data> node.

Map Categories

The list below contains a list of all supported entry types. Type 0 is special. It can't be used when submitting maps to the API and merely serves as a fallback in case a type is deleted. This list is also returned in the "info" mode.

Id Type Name Description
0unknownUnknown category. Can't be selected by the user. If one of your map has this category, update its category list please.
1creativeThis map was (partially) built using creative mode. This is no indication if creative mode is still enabled or not.
2editedThis map was edited in a save file editor. This only concerns significant edits like creating items, restoring things on the map that were taken or removing things.
3natureThis map integrates nature rather than building everything on foundations or in the sky
4foundationsMost things are built on foundations
5global gridThe majority of foundations on this map are aligned on a global grid
6complete researchResearch has been completed
7complete altsAll alternate recipes have been unlocked
8all productsAll products are made on this map
9outpostThis map utilizes outposts and ships processed materials around rather than raw materials
10central factoryThis map makes everything in a central factory
11belts onlyBelts only, no vehicles for material transport
12clean energyThis factory uses clean energy only (biomass + geothermal)
13nuclear energyThis factory features nuclear energy
14trainsThis factory relies on trains
15carsThis factory relies on trucks and tractors
16full minimapThe minimap is fully explored
17perfect ratiosAll ratios in this factory are perfect or as close to perfect as possible
18sky baseMost things are built high above the ground
19untouched natureNo leaves, flowers, wood, berries, nuts or mushrooms were taken, or they were restored using an editor
20untouched artifactsNo artifacts were taken, or they were restored using an editor
21untouched slugsNo slugs were taken, or they were restored using an editor
22untouched animalsNo aminals were slain, or they were restored using an editor
23funThese are maps purely made for the entertainment of the player. For example large arrays of jump pads and map encompassing train tracks
24artMap that is art, either via minimap or ingame pixel art for example
25landmarksMap that contains large buildings created for aesthetic purposes, for example real looking skyscrapers or big suspension bridges
26warehouseMap features a warehouse style location where every item is obtainable from containers with the possible exclusion of raw and nuclear materials as well as player equipment
27challengeThis map solves an arbitrary challenge or provides one for the player
28spaghettiNot a lot of care has been taken when placing belts, going for a more direct route
29perfect alignmentBelts are neatly aligned to 90°, even if it means much longer belts
30OCD CompleteEverything is perfect. Belt layouts, machine placements, ratios. Just everything

Conflicts

Some categories can't be used in combination with some other categories. The list below contains the conflicts.
Note: The list is bidirectional. If category n conflicts with m, the entry for m will also list n as conflict. A category that lists itself as conflict is essentially disabled. The list is also given in the "info" API command. Category 0 is stipped from the list below to shorten it, but it is present in the API command.

Id Name Conflicts
3nature4, 18
4foundations3
9outpost10
10central factory9
11belts only14, 15
12clean energy13
13nuclear energy12
14trains11
15cars11
18sky base3
28spaghetti29, 30
29perfect alignment28
30OCD Complete28

XML Elements and Attributes

Unless otherwise stated, values are given as the text of an Xml Node.

Map Id Format

A valid Id is a UUID, for example 7a8b0a88-284e-4473-9b6b-84e1e33d8051. Do not enclose it in brackets. Most API calls accept the regular id as well as the hidden id. You still need to be the owner of the map to modify it, even if the hiden id is supplied.

Map Data

The structure of a map is as follows:

  • id: The map id. Not present in the "details" command.
  • publishdate: Date this map was uploaded
  • name: File name of the map (including .sav extension)
  • description: Description of this map
  • version: Game version this map was created with
  • public: 0=private, 1=public
  • user: User name as value and id as attribute. Only present when the "list" or "details" command is used. it's not set for actions on your own map because your name can be obtained via the info command.
  • hidden_id: Hidden id that can be used to share private maps. Not present in the "list" or "details" command.
  • size: Sizes of this save file
    • real: Real file size in bytes
    • compressed: Transmitted file size in bytes
  • categories: Zero or more category items
    • category: Category id

Number Format

Numbers are given in "Invariant Culture". Decimal symbol is always a dot .
No number grouping is performed.

Dates

Dates are given in Unix time. In case you are not familiar with it, unix time is the number of seconds since 1970-01-01 00:00:00 UTC. Many programming languages operate on this system. You need to convert if yours doesn't but it's very simple:

  1. Create a new date object of the time given above. Make sure the time zone is UTC or GMT.
  2. Now add the number of seconds to it. Most date libraries will properly convert this.
  3. Finally, convert the object to your local time
Going back (no API method as of now needs a time stamp):
  1. Convert the date object to UTC or GMT
  2. Create a new date object of the time given above. Make sure the time zone is UTC or GMT.
  3. Subtract the the 1970 date object from the current one
  4. Extract the total number of seconds

Time Spans

For things that are not entire dates but just a certain amount of time, times are given in seconds. An example would be the total play time stored in a save file.

Arrays

To submit values that are arrays, specify the key-value pair multiple times with [] as key suffix. Request body for setting two categories on a map:
key=99cd7ebc-a04c-42be-aa2e-f8bbfe92ad46&id=fc1536c0-f6e2-4697-9d0f-88fb0beebb14&category[]=2&category[]=4
Array keys must always specify the [] suffix even if only used once.

Mode: test

This mode tests the API. It simply returns all fields you sent in the data node. This mode requires a valid API key even though no personal data is accessed. This means you can use this to test the validity of the key too.

Anonymous

Both

Fields

Any

Response

All sent fields are returned (excluding any uploaded file)

Mode: info

Returns the username as well as the list of your maps.

Anonymous

Both

Fields

None

Response

  • user: User name as value and id as attribute. Anonymous id is '0' and the name will be an empty string.
  • categories: All available categories and the conflict list
    • list: The list of all categories
      • category: Category. The id is supplied as attribute of this entry
        • name: Short category name
        • description: Category description
    • conflicts: The list of categories that are mutually exclusive to other categories. See the "Map Categories" tab for more information.
      • conflict: Category with conflicts. The category id is supplied as category attribute of this entry
        • category: Category that conflicts with this one. This entry is repeated as necessary
  • maps: List of all your maps, absent on anonymous requests. The layout of a map property is shown in the "Data Types" tab.

Mode: details

Returns a single map entry

Anonymous

Both

Fields

  • id: The map id
The details can always be viewed using the hidden id. With the regular id, you either need to be the owner or the map must be public.

Response

The data property of the answer will be a map entry. The "id" and "hidden_id" fields will be absent from the entry.

Mode: edit

Edits an existing map

Anonymous

No

Fields

Only the "id" field is required. All other fields are optional and if not specified, will leave that map property unchanged.

  • id: The map id. The hidden id is allowed too but you still need to be the owner of this map
  • name: The new file name. .sav is added if missing.
  • description: Map description
  • category[]: Map category. Repeat this field for each category
  • public: Map visibility. 1=public, 0=hidden

Response

Returns the updated map entry. See the "info" help on how this entry looks like

Mode: del

Deletes a map

Anonymous

No

Fields

  • id: The map id. The hidden id is allowed too but you still need to be the owner of this map

Response

None. Check the general 'success' field

Mode: add

Uploads a map. Data must be sent as multipart/form-data

Anonymous

No

Fields

  • map: The map itself
Tip: Compress the map before uploading it. The server accepts gzip compressed maps. Because map data is very repetitive you can save up to 95%. The compression is auto detected.

Response

The map information. See the "info" command on how this structure looks.

Mode: newid

Generates a new hidden id for a map.

Anonymous

No

Fields

  • id: The map id. The hidden id is allowed too but you still need to be the owner of this map

Response

The new hidden id.

Mode: list

Lists public maps

Anonymous

Yes

Fields

All fields are optional

  • user: The user name. Limits the map list to maps from this user. Default=All users
  • category: Any category id. Limits the map list to maps that contain this category. Default=All categories
  • page: The page. Default=1

Response

  • more: If set to true, it means you can increment the page parameter by 1 to get more maps
  • maps: A list of maps. See the "info" command for help on this structure. Note: Sensitive fields are stripped from map entries in this call.

Non-Api Functions

These functions can be used as part of the API but work differently. They are regular HTTP GET requests without an API key. For private maps, you have to supply the "hidden id" instead of the regular id.

Preview Image

URL: https://cable.ayra.ch/satisfactory/maps/preview/?map=<map-id>
Delivers a 1000x1000 png image with a preview of the save file.

Download

URL: https://cable.ayra.ch/satisfactory/maps/download/?map=<map-id>
Delivers the save file itself. Note: For this to work your client must support gzip encoding.

Copyright © 2019 by Kevin Gut 📧 | More services | Generated for 3.232.129.123