API
Contents
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
- Every route uses the
/status
endpoint
Available servers
Note: Secondary adress listings are the cfx.re proxy- usage is the same.
Address | Server Name | Additional Information |
---|---|---|
server.tycoon.community:30169
tycoon-w8r4q4.users.cfx.re |
Server 1 | OneSync server, may not be as stable as the other servers |
server.tycoon.community:30122
tycoon-2epova.users.cfx.re |
Server 2 | |
server.tycoon.community:30123
tycoon-2epovd.users.cfx.re |
Server 3 | |
server.tycoon.community:30124
tycoon-wdrypd.users.cfx.re |
Server 4 | |
server.tycoon.community:30125
tycoon-njyvop.users.cfx.re |
Server 5 (Beta) | Beta server, data could end up being different compared to other servers |
na.tycoon.community:30120
tycoon-2r4588.users.cfx.re |
Server 6 | Despite the NA subdomain, these servers are not hosted in North America and are also European |
na.tycoon.community:30122
tycoon-npl5oy.users.cfx.re |
Server 7 | |
na.tycoon.community:30123
tycoon-2vzlde.users.cfx.re |
Server 8 | |
na.tycoon.community:30124
tycoon-wmapod.users.cfx.re |
Server 9 | |
na.tycoon.community:30125
tycoon-wxjpge.users.cfx.re |
Server A | |
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
On 19 June 2021, Tycoon's CDN now 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 permanent and available at https://cdn.tycoon.community/servers.json
.
File contents:
{ "servers": [ { "id": "w8r4q4", "owner": "tycoon", "number": "1", "endpoint": "status/widget/players.json", "name": "Server 1" }, { "id": "2epova", "owner": "tycoon", "number": "2", "endpoint": "status/widget/players.json", "name": "Server 2" }, { "id": "2epovd", "owner": "tycoon", "number": "3", "endpoint": "status/widget/players.json", "name": "Server 3" }, { "id": "wdrypd", "owner": "tycoon", "number": "4", "endpoint": "status/widget/players.json", "name": "Server 4" }, { "id": "njyvop", "owner": "tycoon", "number": "5", "endpoint": "status/widget/players.json", "name": "Server 5 (Beta)" }, { "id": "2r4588", "owner": "tycoon", "number": "6", "endpoint": "status/widget/players.json", "name": "Server 6" }, { "id": "npl5oy", "owner": "tycoon", "number": "7", "endpoint": "status/widget/players.json", "name": "Server 7" }, { "id": "2vzlde", "owner": "tycoon", "number": "8", "endpoint": "status/widget/players.json", "name": "Server 8" }, { "id": "wmapod", "owner": "tycoon", "number": "9", "endpoint": "status/widget/players.json", "name": "Server 9" }, { "id": "wxjpge", "owner": "tycoon", "number": "A", "endpoint": "status/widget/players.json", "name": "Server A" }, { "id": "dgpvx3", "owner": "tycoon", "number": "L", "endpoint": "sessionmanager/players.json", "name": "[LITE] Transportation" } ], "notice": "Proxy may not always be available, even if the server is", "template": "https://${owner}-${id}.users.cfx.re/${endpoint}" }
API Keys
TL;DR: Create a new key using /api key new
Add charges using /api key refill
(adds 1000 charges for $1M)
The API requires an API Key to access most features.
Each 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 key refill
command at the cost of $1000 (in-game money) per charge. Any user can generate an API key; this key is said user's private key. (Make sure you keep it safe!) To generate a key, use the /api key new
command in game. If you already have a key generated, the old one will be deleted and a new one will take its place. When you generate a 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 key 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.
As the API has become more and more commonly used, it is now possible to restrict access to your player/personal data so that only your API key can query it. In order to restrict access, do /api lock
in game, and privacy will be enabled.
API Endpoints
General notes
- API keys should be sent as headers, like such:
X-Tycoon-Key: [api-key]
- Each endpoint here will mention if a 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 charges remaining after the request.
Standard status codes
- 401 Unauthorized - An API key is required for the route
- 402 Payment Required - No API charges remaining
- 403 Forbidden - Invalid API key
- 404 Not Found - Invalid API route
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 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 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 billionares, etc.
Response:
- Code:
200 OK
- Requires key:
false
Response data: The response is a large CSV (though in reality its seperated with semi-colons) 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
Fetches the current skill rotation for the servers
Response:
- Code:
200 OK
- Requires key:
true
Response data:
{ "bonus": 11, // Bonus percentage (10-30) "skill": "Cargo Piloting" // Name of the skill it applies to }
Server-specific endpoints
GET /weather.json
Fetches info about the current weather on the server, with how long until it changes.
Response:
- Code:
200 OK
- Requires key:
true
Response data: The response is a JSON object containing weather data.
{ "time_remaining": 1497, // Time in seconds until next weather change "current_weather": "drizzling" // The current weather on the server }
GET /forecast.json
Fetches info about the current forecast on the server.
Response:
- Code:
200 OK
- Requires key:
true
Response data: The response is a JSON object containing forecast 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 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 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 the players last 20 locations, which is about ~4 seconds of data.
Note: the position history doesnt seem to apply to every player, so make sure to check if this data exists first!
Response:
- Code:
200 OK
- Requires 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 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 key:
true
Response data:
{ "code": "200", "stat": "toll_paid", "top": [ { "amount": 14765137, "username": "xxxxx", "user_id": 41306 }, ... ] }
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 |
Garages | 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 |
Response:
- Code:
200 OK
- Requires 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 key:
true
Response data:
{ "code": "200", "user_id": 41306, "discord_id": 138725221749358592, "type": "linked" }
GET /getuserbiz/[vRPid]
Get users owned businesses.
Response:
- Code:
200 OK
- Requires 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 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 /data/[vRPid]
Get users data, such as inventory, clothing, and more.
Response:
- Code:
200 OK
- Requires 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": { "group_card|mechanic|Mechanic": { "amount": 10 } } } ... }
GET /dataadv/[vRPid]
Get users data with more detailed item info (weight, name, etc).
Response:
- Code:
200 OK
- Requires 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 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]
Get users wealth
Note: User Must be online to obtain wealth
Response:
- Code:
200 OK
- Requires key:
true
Response data:
{ "user_id": 256983, "wallet": 101256983, "bank": 0, "loan": 0, "code": "200" }
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 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 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 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 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 key:
true
Response data:
[39] // 0: Perk amount
GET /faction/balance.json
Returns the factions balance
Response:
- Code:
200 OK
- Requires key:
true
Response data:
[107965.0] // 0: Faction balance
GET /faction/info.json
Returns some basic faction info
Response:
- Code:
200 OK
- Requires key:
true
Response data:
{ "tag": "The Corrupt", "faction_id": 56, "name": "CoCo" }
[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' status/widget/players.json
.
Response:
- Code:
200 OK
- Requires 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 ], ... ] }