API
Contents
- 1 Transport Tycoon API
- 1.1 Available servers
- 1.2 Private Keys
- 1.3 Public Keys
- 1.4 Privacy related options
- 1.5 API Endpoints
- 1.5.1 General notes
- 1.5.2 Endpoints List
- 1.5.3 Main endpoints
- 1.5.4 Server-specific endpoints
- 1.5.5 Global endpoints
- 1.5.5.1 GET /top10/[statName]
- 1.5.5.2 GET /racing/map/[id]
- 1.5.5.3 GET /config/[resourceName]
- 1.5.5.4 GET /snowflake2user/[discordId]
- 1.5.5.5 GET /streak/[vRPid]
- 1.5.5.6 GET /getuserbiz/[vRPid]
- 1.5.5.7 GET /ownedvehicles/[vRPid]
- 1.5.5.8 GET /trunks/[vRPid]
- 1.5.5.9 GET /deadliest_catch.json
- 1.5.5.10 GET /stats/[vRPid]
- 1.5.5.11 GET /storages/[vRPid]
- 1.5.5.12 GET /racing/races/[vRPid]
- 1.5.5.13 GET /data/[vRPid]
- 1.5.5.14 GET /dataadv/[vRPid]
- 1.5.5.15 GET /chest/[chestName]
- 1.5.5.16 GET /wealth/[vRPid]
- 1.5.5.17 GET /iteminfo/[itemid]
- 1.5.6 Faction endpoints
- 1.5.7 Company endpoints
- 1.5.8 [LITE] endpoints
Transport Tycoon API
The api for TT follows a few standard principles:
- Certain routes will return different data based on server
- Every server requires a different URL to fetch data from, instead of one standardized URL
- Legacy routes use the
/status
path in urls.v1.api.tycoon
addresses are automatically routed with/status
.
Available servers
Note: Secondary adress listings are the cfx.re proxy- usage is the same.
Address | Server Name | Additional Information |
---|---|---|
v1.api.tycoon.community/main (currently unavailable)
tycoon-2epova.users.cfx.re/status |
Server 1 | |
v1.api.tycoon.community/beta (currently unavailable)
tycoon-njyvop.users.cfx.re/status |
Server 2 (Beta) | Beta server, data could end up being different compared to other servers |
lite.tycoon.community
tycoon-dgpvx3.users.cfx.re |
[LITE] Transportation | Runs a different gamemode, does not respond to standard Transport Tycoon API calls. sessionmanager/players.json will fetch a list of players.
|
Server list CDN file
Tycoon's CDN hosts a permanent JSON file that returns a list of servers, their player information endpoint, and a template for formatting API URL calls to each server. In addition to the main Transport Tycoon servers, it also includes information for the [LITE] Transportation server.
The file is available at https://cdn.tycoon.community/servers.json
.
Private Keys
TL;DR: Create a new private key using /api private new
Add charges using /api private refill
(adds 1000 charges for $1M)
Add x
charges using /api private refill <x>
(adds <x> charges for $1000 * x
)
The API requires a private key to access most features.
Each private key has a limited amount of API calls (also called charges), which are consumed every time an API call is made using the key. Additional charges can be purchased in game using the /api private refill
command at the cost of $1000 (in-game money) per charge. Any user can generate a private key (Make sure you keep it safe). To generate a private key, use the /api private new
command in game. If you already have a private key generated, the old one will be deleted and a new one will take its place. When you generate a private key for the first time, it will come with some free charges allowing you to test the API for free. The API key can be copied using the /api private copy
command, which will display the key for you to copy to your clipboard. Any user with a linked Discord account will receive a Discord role upon refilling their keys.
Donating API charges
When using services created by other players, they usually use their own private key. If you wish to support them, you can donate charges to them with /api donate <user id> <amount>
- where
<user id>
is the ID of the player whose key is being used for a given service<amount>
is the amount of charges you want to donate (each charge is $1000).- The minimum amount of charges you can donate is 1000.
If the receiving player is online and in the same server as you, they will get a notification of receipt.
Public Keys
Public keys are keys that can be used to access a players account information without needing that player's private key and charges.
The public key is not valid by itself and must be included alongside a valid private key
The public key can be be used as an authorization/identification token, changing the target account from the private key's owner to the public key's owner for commands whose data is determined by public/private key ownership (i.e deadliest_catch, faction endpoints) or, allowing access to data for accounts with API locks in place.
To generate a public key, use /api public generate
You may restrict access to your own data with the /api lock
command in-game. When your API information is locked, data is inaccessible to anyone requesting it unless the request includes your public or private key.
API Endpoints
General notes
- Private keys should be sent as headers, like such:
X-Tycoon-Key: [api-key]
- Public keys are sent with the
X-Tycoon-Public-Key: [public-key]
header - Each endpoint here will mention if a private key is required to be used. Note that currently, every route which requires a key will only use 1 charge per request.
- Typically, this data is returned as JSON, unless explicitly mentioned.
- Most routes will have a response header called
X-Tycoon-Charges
, which will give you the number of private key charges remaining after the request.
Standard status codes
- 400 Bad Request - invalid endpoint
- 401 Unauthorized - A private key is required for the route
- 402 Payment Required - No API charges remaining
- 403 Forbidden - Invalid private key or invalid public key
- 404 Not Found - Invalid API route
Endpoints List
GET /endpoints.json
Returns all available endpoints of the target server. This returned value should always be the same regardless of which server it's used on (excluding beta and/or event).
Response:
- Code:
200 OK
- Requires private key:
true
Response data:
[ ... "/faction/balance.json", "/charges.json", ... ]
Main endpoints
GET /alive
This endpoint is simply designed to be used as a status check for the API.
Response:
- Code:
204 NO CONTENT
- Requires private key:
false
GET /charges.json
Used to check how many charges are left on the specific key. Will not use an API charge.
Response:
- Code:
200 OK
- Requires private key:
true
Response data: An array where index 0 is the amount of charges remaining
[xxxx]
GET /economy.csv
Fetches general info about the economy of TT, such as the amount of billionaires, etc.
Response:
- Code:
200 OK
- Requires private key:
false
Response data: The response is a large CSV file separated with semicolons, with a lot of data about the economy in Transport Tycoon.
Time;Debt;Money;Debts;Millionaires;Billionaires;Users;Players 1580811614;14255411890;1106983649214;10361;14458;179;316329;40
GET /skillrotation.json
GET /sotd.json
Fetches the current skill rotation for the servers
Response:
- Code:
200 OK
- Requires private key:
true
Response data:
{ "aptitude": "trucking/postop", // Skill component "short": "PostOP", "bonus": 33, // Bonus Percentage (25-50) "skill": "PostOP" // Name of the skill it applies to }
GET /racing/tracks.json
Fetches general info about TT races.
Response:
- Code:
200 OK
- Requires private key:
true
Response data:
{ ... { "index": 1, "name": "TTfred", "wr": { "vehicle": "On Foot", "time": 759614, "date": 1644171709000.0, "name": "IFS™" }, "class": "Cars", "length": 28167, "type": "ground" }, ... }
GET /dealership.json
Fetches data about the current dealership rotation.
Response:
- Code:
200 OK
- Requires private key:
true
Response data:
{ "Premium": [ { "name": "Patriot Stretch", "price": 500000, "model": "patriot2" }, ... ], "Offroad": [ { "name": "Bifta", "price": 5000, "model": "bifta" }, ... ], ... }
Server-specific endpoints
GET /weather.json
Fetches info about the current weather on the server, including how long until it changes.
Response:
- Code:
200 OK
- Requires private key:
true
Response data:
{ "minute": 36, "hour": 16, "weather": "CLEAR" // The current weather on the server }
GET /forecast.json
Fetches info about the current forecast on the server.
Response:
- Code:
200 OK
- Requires private key:
true
Response data:
[ 'CLEAR', 'OVERCAST', 'EXTRASUNNY', 'CLEARING', 'RAIN', 'RAIN', 'RAIN', 'CLOUDS', 'FOGGY' ]
GET /airline.json
Returns the current active destinations for players doing airline.
Response:
- Code:
200 OK
- Requires private key:
true
Response data:
{ "875": [ // Route number "Velum", // Vehicle model / name { // Destination "z": 20.51197052002, "y": 6583.7412109375, "x": 2777.1384277344, "h": 47.063835144043, "airport": "MGA" "name": "Mount Gordo Terminal 3" }, false, // Boarding/arrived (set once the plane is unloading) 41306 // vRP id ] }
GET /players.json
Fetches basic data about the current players on the server.
Response:
- Code:
200 OK
- Requires private key:
false
Response data:
{ "players": [ [ "xxxx", // [0] user name 895, // [1] source id 41306 // [2] vRP id ], ] }
GET /map/positions.json
Fetches the data of players, including position and vehicle data, along with each player's last 30 locations separated by around 500 milliseconds.
Note: the position history doesn't seem to apply to every player, so make sure to check if this data exists first!
Response:
- Code:
200 OK
- Requires private key:
true
Response data:
{ "players": [ [ "xxxx", // Player name 820, // Source ID (FiveM assigned plyr ID) 41306, // vRP id { // Position "z": 16.24852180480957, // Current X coordinate "y": 5180.30029296875, // Current Y coordinate "x": -2179.143798828125 // Current Z coordinate }, { // Vehicle Data "vehicle_type": "helicopter", "vehicle_name": "Maverick", "vehicle_label": "MAVERICK", "vehicle_class": 15, // Vehicle class id, see https://docs.fivem.net/natives/?_0x29439776AAA00A62 "vehicle_spawn": "maverick", "owned_vehicles": { "trailer": "drybulktr", "cab": "urnext", "car": "rc350" }, "vehicle_model": -1660661558, // Model hash "trailer": "", "has_trailer": false }, { // Job data "group": "firefighter", "name": "Firefighter" }, [ // Incremental position history [ 78, // Incremental index 3612.8, // X 3766.1, // Y 32.3 // Z ], [ 79, 3612.8, 3766.1, 32.3 ], ... ] ] ], "caches": 6648, "requests": 6834 }
GET /widget/players.json
Fetches basic data about the current players on the server.
Response:
- Code:
200 OK
- Requires private key:
false
Response data:
{ "server": { "number": "1", "dxp": [ true, // Dxp active "xxxx", // Dxp host 22474824, // Time remaining 0, // Extra DXP time 6325176 // How long the Dxp has been active ], "limit": 128, // Player limit "region": "OS", "uptime": "14h 25m", "beta": "", "motd": "", "name": "" }, "players": [ [ "xxxx", // Username 895, // Source ID (FiveM assigned plyr ID) 434912, // vRP id "img", // Avatar url false, // Staff "Train Conductor", // Job false // Donator ] ] }
Global endpoints
These endpoints should return data regardless of the server they are run on (excluding Beta and [LITE]). These endpoints are related to user data.
GET /top10/[statName]
Fetches the top 10 info for the specific stat. Available stats:
firefighter_streak_record omni_void_leaderboard ems_streak_record ems_deliveries houses_crafted toll_paid trap_paid drops_collected quarry_excavate quarry_coop quarry_deliver quarry_solo vehicles_crafted eastereggs_pickup maid_maxscans maid_ticket
Response:
- Code:
200 OK
- Requires private key:
true
Response data:
{ "code": "200", "stat": "toll_paid", "top": [ { "amount": 14765137, "username": "xxxxx", "user_id": 41306 }, ... ] }
GET /racing/map/[id]
Fetches the name and blip information about a race.
Response:
- Code:
200 OK
- Requires private key:
true
Response data:
{ "finish": { "blip": 26739008, "x": -2169.2763671875, "z": 16.877534866333, "y": 5195.4794921875, "h": 0.68444913625717 }, "checkpoints": [ { ... }, ... ], "start": { ... }, "name": "TTfred" }
GET /config/[resourceName]
Pulls the config.lua of specific server resources which support this. Available resources:
Type/Job | Config Path |
---|---|
Bus Job | omni_busdriver |
Business | omni_businesses |
Garbage Collector | omni_garbage |
Heli Job | omni_helitour |
EMS/Paramedic | omni_paramedic |
Conductor | omni_pax |
Postop Ground | omni_postop_ground |
Postop Air | omni_postop_air |
Self Storages | omni_self_storage |
Houses, Stuff in Houses | vrp |
RTS Ground (Vehicles, Locations) | rts_ground |
Tycoons Custom Vehicle Classes | custom-vehicle-classes |
Response:
- Code:
200 OK
- Requires private key:
false
Response data: The lua file which configures the given resource.
--[[ omni_businesses CONFIG 1/1 (sh_businesses.lua) ]]-- BUSINESSES = { { name = "Jonny Tung", id = "biz_tung", cost = 25*10^6, reqlvl = {"@business.business.>61"}, visuallvl = "62", position = {name = "Jonny Tung", x = -902.894836, y = -227.015121, z = 39.818169, h = 331.733337}, -- glitchdetector (3) special = { {type = "special", name = "Location", x = -905.682617, y = -232.291809, z = 39.818180, h = 137.194992}, {type = "garage", name = "Garage", x = -900.111206, y = -201.733612, z = 38.247940, h = 71.658554}, -- glitchdetector (3) }, } ...
GET /snowflake2user/[discordId]
Converts the discord snowflake into a vRP id, for use in other endpoints.
Response:
- Code:
200 OK
- Requires private key:
true
Response data:
{ "code": "200", "user_id": 41306, "discord_id": 138725221749358592, "type": "linked" }
GET /streak/[vRPid]
Get users streak.
Response:
- Code:
200 OK
- Requires private key:
true
Response data:
{ "data": { "days": 72, "record": 49, "streak": 49 }, "code": "200", "user_id": 56112 }
GET /getuserbiz/[vRPid]
Get users owned businesses.
Response:
- Code:
200 OK
- Requires private key:
true
Response data:
{ "code": "200", "businesses": { "biz_vespucci_masks": 14 // [id]: level }, "user_id": 41306 }
GET /ownedvehicles/[vRPid]
Get users owned vehicles.
Response:
- Code:
200 OK
- Requires private key:
true
Response data:
{ "code": "200", "vehicles": { "trailers2": ["trailer", 2750], // Model: array[class, inventory_size] "vestra": ["aircraft", 30], "bmx": ["bicycle", 10], "neon": ["car", 10], "hakuchou": ["bike", 10], "hauler2": ["cab", 10] }, "user_id": 41306 }
GET /trunks/[vRPid]
Get users vehicle inventories.
Response:
- Code:
200 OK
- Requires private key:
true
Response data:
{ "user_id": 256983, "code": "200", "trunks": [ { "inventory": {}, "type": "aircraft", "vehicle": "a320" }, { "inventory": { "upgrade_kit_primo2": { "amount": 1 }, "fridge_airline_meal": { "amount": 668 } }, "type": "aircraft", "vehicle": "a330neo" }, { "inventory": {}, "type": "helicopter", "vehicle": "volatus" } ] }
GET /deadliest_catch.json
Get users placed pots.
Response:
- Code:
200 OK
- Requires private key:
true
- Accepts Public Key:
true
Response data:
[ ..., { "position": { "y": -5161.54150390625, "z": 0.21182405948638, "x": 4909.94287109375 }, "age": 951507, // Seconds since pot was placed "type": "crab" }, ... ]
GET /stats/[vRPid]
Returns users stats
Response:
- Code:
200 OK
- Requires private key:
true
Response data:
{ ... { "stat": "quarry_coop", "name": "Contributed Quarry Deliveries", "amount": 446 }, ... }
GET /storages/[vRPid]
Returns users storages
Response:
- Code:
200 OK
- Requires private key:
true
Response data:
{ "user_id": 256983, "code": "200", "storages": [ { "inventory": { "gut_knife_fade|132": { "amount": 1 }, "liberty_voucher_goods": { "amount": 168 } }, "name": "bctp" }, { "inventory": {}, "name": "tsu" } ] }
GET /racing/races/[vRPid]
Returns users racing stats
Response:
- Code:
200 OK
- Requires private key:
true
Response data:
{ ... { "track_id": -1837157281, "time": 50636, "vehicle": "Visione", "achieved": 1642359702000.0, "user_id": 56112 }, ... }
GET /data/[vRPid]
Get users data, such as inventory, clothing, and more.
Response:
- Code:
200 OK
- Requires private key:
true
Response data:
{ // Too much data to display and annotate, try and experiment, and dont be afraid to ask around! "code": "200", "data_type": "data_offline", "user_id": 41306, "data": { "inventory": { "job_card|mechanic|Mechanic": { "amount": 10 } } } ... }
GET /dataadv/[vRPid]
Get users data with more detailed item info (weight, name, etc).
Response:
- Code:
200 OK
- Requires private key:
true
Response data:
{ "amount": 185, "weight": 0.0, "name": "<span style=\"color:lawngreen\">Sandwich</span>" },
GET /chest/[chestName]
Allows you to fetch the items inside of chests.
Chest naming scheme cheatsheat:
- Fetch vehicle storage:
u[vRPid]veh_[vehClass]_[model]
- Fetch home storage:
u[vRPid]home
- Fetch backpack storage:
u[vRPid]backpack
- Fetch faction storage:
self_storage:[vRPid]:faq_[factionId]:chest
- Other storage:
self_storage:[vRPid]:[storageId]:chest
Response:
- Code:
200 OK
- Requires private key:
true
Response data:
{ "data": { "refined_flint": { "amount": 288 }, "scrap_gravel": { "amount": 48 }, "tcargodust": { "amount": 1650 }, "refined_sand": { "amount": 504 } }, "code": "200", "data_type": "chest", "chest": "self_storage:41306:faq_56:chest" }
GET /wealth/[vRPid]
Returns users wealth
Note: User Must be online to obtain wealth Data
Response:
- Code:
200 OK
- Requires private key:
true
Response data:
{ "user_id": 256983, "wallet": 101256983, "bank": 0, "loan": 0, "code": "200" }
GET /iteminfo/[itemid]
Returns item info
- Item IDs returned by the API in requests such as DataAdv can be used as-is
Response:
- Code:
200 OK
- Requires private key:
true
Response data:
{ "item_id": "itemid", // Same as input, always returned "name": "Item Name", "weight": 0.0, "description": "Description", // As seen in the in-game M-menu (HTML included) "exists": true // Does the requested item id resolve to an actual item? }
Faction endpoints
This data also fits under the "Global endpoint" category, however, there are many faction-related endpoints, so it's simpler to combine them into one small section.
Do note, all endpoints except GET /getuserfaq/[vRPid]
are related to the faction the key creator or public key is in and may require a certain rank in the faction.
GET /getuserfaq/[vRPid]
Returns the faction the user is in, if in any.
Response:
- Code:
200 OK
- Requires private key:
true
Response data:
{ "is_in_faction": true, "faction_id": 56, "code": "200", "user_id": xxxxx }
GET /faction/size.json
Returns the amount of members in faction.
Response:
- Code:
200 OK
- Requires private key:
true
- Accepts Public Key:
true
Response data:
[787] // 0: Member count
GET /faction/members.json
Returns the info of the members in a faction.
Response:
- Code:
200 OK
- Requires private key:
true
- Accepts Public Key:
true
Response data:
{ // Most of this data is self explanatory "earned": 2199936, "management": 0, "user_id": 1, "admin": 0, "recruiter": 1, "username": [ // Username as UTF-16 character codes 67, 111, 108, 108, 105, 110, 115 ], "joined": 1608662095000.0 // Timestamp of when the user joined } ]
GET /faction/perks.json
Returns the amount of perks a faction has
Response:
- Code:
200 OK
- Requires private key:
true
- Accepts Public Key:
true
Response data:
[39] // 0: Perk amount
GET /faction/balance.json
Returns the factions balance
Response:
- Code:
200 OK
- Requires private key:
true
- Accepts Public Key:
true
Response data:
[107965.0] // 0: Faction balance
GET /faction/info.json
Returns some basic faction info
Response:
- Code:
200 OK
- Requires private key:
true
- Accepts Public Key:
true
Response data:
{ "tag": "The Corrupt", "faction_id": 56, "name": "CoCo" }
Company endpoints
GET /companies/rts/ground.json
Returns ground vehicles avaiblile to deliver
Returns empty if not opened the menu
Response:
- Code:
200 OK
- Requires private key:
true
- Accepts Public key:
true
Response data:
{ "vehicles": [ "brutus ", "infernus", "fugitive", "romero", "formula", "zr350ta", "iwagen", "blazer3" ] }
GET /companies/pigs/party.json
Returns information of ongoing pigs heist
Response:
- Code:
200 OK
- Requires private key:
true
Response data:
{ "master": { // Heist Leader "source": 662, // Server player id "ready": true, "cut": 2 // Number of successful heists }, "take": 0, // Total stolen money of current heist "slaves": [ { "source": 661, // Server player id "ready": true, "cut": 1 // Number of successful heist locations } ], "kills": 0, // Number of A.I. enemies killed "limit": 1024 // Total players allowed in a heist - hardcoded 1024 }
[LITE] endpoints
These endpoints are specific to the [LITE] Transportation server and are not shared with the main Transport Tycoon servers.
GET sessionmanager/players.json
Returns a list of players, similar to the main servers' widget/players.json
.
Response:
- Code:
200 OK
- Requires private key:
false
Response data:
{ "server": { "number": "", "dxp": [false], "motd": "", "beta": "", "name": "[LITE] Transportation", "region": "", "uptime": "50h 12m", "limit": 32 }, "players": [ [ "Username1", "91", // Source ID? (FiveM-assigned player ID) "91", false, false, "Trucker", // Job false ], ... ] }