Difference between revisions of "API"

From Tycoon Gaming
m (Fix awkward/incorrect grammar/spelling on API page)
(33 intermediate revisions by 7 users not shown)
Line 1: Line 1:
== Transport Tycoon API ==
+
= Transport Tycoon API =
Root API URI is het adres van de server
 
  
API is beschikbaar per server instantie
+
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 <code>/status</code> endpoint
  
=== API Keys ===
+
== Available servers ==
 +
<span style="color:red">Note</span>: Secondary adress listings are the cfx.re proxy- usage is the same.
 +
{| class="article-table sortable" style="width: 100%;" |
 +
!data-sort-type="text" style="width: 33%" |'''Address'''
 +
!data-sort-type="text" style="width: 23%" |'''Server Name'''
 +
!data-sort-type="text" style="width: 43%" |'''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. <code>sessionmanager/players.json</code> will fetch a list of players.
 +
|}
  
TL;DR:
+
=== Server list CDN file ===
Maak een nieuwe key met '''/api key new'''
 
  
Voeg charges toe met '''/api key refill''' (voegt 1000 charges voor $1M)
+
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 <code>https://cdn.tycoon.community/servers.json</code>.
  
 +
'''File contents:'''
 +
<pre>{
 +
  "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}"
 +
}</pre>
  
De API vereist een API-sleutel om toegang te krijgen tot de meeste functies.
+
== API Keys ==
  
Elke sleutel heeft een beperkt aantal API Calls (ook wel charges genoemd), die elke keer dat een API Call wordt gedaan met de key wordt verbruikt.
+
TL;DR: Create a new key using <code>/api key new</code>
  
Extra cahrges kunnen in de game worden gekocht met de '''/api key refill''' command voor de kost van $1000 (in-game geld) per charge.
+
Add charges using <code>/api key refill</code> (adds 1000 charges for $1M)
  
Elke gebruiker kan een API Key genereren, deze key is de privésleutel van de gebruiker.
+
The API requires an API Key to access most features.
  
Om een key te genereren, gebruikt u de'''/api key new''' command in-game.
+
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 <code>/api key refill</code> 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 <code>/api key new</code> 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 <code>/api key copy</code> 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.
  
Als u al een key heeft gegenereerd, wordt de oude verwijderd en komt er een nieuwe in de plaats.
+
== Privacy related options ==
  
Wanneer u voor de eerste keer een key genereert, worden er enkele gratis charges voor in rekening gebracht, zodat u de API gratis kunt testen.
+
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 <code>/api lock</code> in game, and privacy will be enabled.
  
De API key kan worden gekopieerd met de '''/api key copy''' command. (Dit zal uw key op het scherm laten zien!)
+
== API Endpoints ==
  
=== Voor developers ===
+
=== General notes ===
De API key moet worden geplaatst als een `X-Tycoon-Key` header.
 
  
=== Key Gerelateerde Endpoints ===
+
* API keys should be sent as headers, like such: <code>X-Tycoon-Key: [api-key]</code>
 +
* 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 <code>X-Tycoon-Charges</code>, which will give you the number of charges remaining after the request.
  
/charges.json
+
==== Standard status codes ====
Geeft het resterende charges terug (geen charges verbruikt om te controleren)
 
  
=== Legenda ===
+
* 401 Unauthorized - An API key is required for the route
type name (gegevenstype en een eigenschapnaam)
+
* 402 Payment Required - No API charges remaining
 +
* 403 Forbidden - Invalid API key
 +
* 404 Not Found - Invalid API route
  
type? name (het gegevenstype kan variëren op basis van de gegevenscontext)
+
<hr></hr>
  
type! name (gegevens bestaan mogelijk niet op basis van gegevenscontext)
+
=== Main endpoints ===
'''Note:''' Array-gegevenstypen bevatten geen benoemde eigenschappen, de namen die hier worden gebruikt, zijn ter verduidelijking
 
  
=== Krijg wereldinformatie voor online spelers ===
+
==== <code>GET /alive</code> ====  
Retourneert een lijst met alle online spelers met positiegegevens.
+
This endpoint is simply designed to be used as a status check for the API.<br>
 +
'''Response:'''
 +
* '''Code:''' <code>204 NO CONTENT</code>
 +
* '''Requires key''': <code>false</code>
  
Hun huidige vervoerswijze en enkele andere details zijn ook opgenomen.
+
==== <code>GET /charges.json</code> ====
 +
Used to check how many charges are left on the specific key. Will not use an API charge.<br>
 +
'''Response:'''
 +
* '''Code:''' <code>200 OK</code>
 +
* '''Requires key''': <code>true</code>
  
Dit eindpunt wordt gebruikt om de live map van de server te produceren.
+
'''Response data:'''
 +
An array where index 0 is the amount of charges remaining
 +
<pre>
 +
[xxxx]
 +
</pre>
  
GET /status/map/positions.json
+
==== <code>GET /economy.csv</code> ====
object
+
Fetches general info about the economy of TT, such as the amount of billionaires, etc.<br>
- int time
+
'''Response:'''
- array[array player] data
+
* '''Code:''' <code>200 OK</code>
-- string name
+
* '''Requires key''': <code>false</code>
-- int source
 
-- int user_id
 
-- vec3 position
 
-- object owned_vehicles
 
--- object[string vehicle_type]!
 
---- string vehicle_spawn
 
-- object vehicle
 
--- int vehicle_class
 
--- string vehicle_type
 
--- int! model
 
--- string! vehicle_label
 
--- string! vehicle_name
 
--- bool? has_trailer
 
--- string! trailer
 
--- string! vehicle_spawn
 
-- object job
 
--- string group
 
--- string name
 
  
=== Krijg servergegevens en online spelers ===
+
'''Response data:'''
Retourneert de servernaam en details, evenals gegevens voor elke online speler.
+
The response is a large CSV file separated with semicolons, with a lot of data about the economy in Transport Tycoon.
 +
<pre>
 +
Time;Debt;Money;Debts;Millionaires;Billionaires;Users;Players
 +
1580811614;14255411890;1106983649214;10361;14458;179;316329;40
 +
</pre>
  
Dit eindpunt wordt gebruikt om de serverlijst te produceren: http://connect.tycoon.community/
+
==== <code>GET /skillrotation.json</code> ====
 +
Fetches the current skill rotation for the servers<br>
 +
'''Response:'''
 +
* '''Code:''' <code>200 OK</code>
 +
* '''Requires key''': <code>true</code>
  
GET /status/widget/players.json
+
'''Response data:'''
object
+
<pre>
- object server
+
{
-- string name
+
  "bonus": 11, // Bonus percentage (10-30)
-- string motd
+
  "skill": "Cargo Piloting" // Name of the skill it applies to
-- string number
+
}
-- string region
+
</pre>
-- string beta
 
-- string uptime
 
-- int limit
 
- array[array player] players
 
-- string name
 
-- int source
 
-- int user_id
 
-- string? avatar
 
-- bool staff
 
-- string job_name
 
-- bool whitelist
 
  
=== Get Online Players ===
+
=== Server-specific endpoints ===
Returns a list of online players
 
  
GET /status/players.json
+
==== <code>GET /weather.json</code> ====
array players
+
Fetches info about the current weather on the server, including how long until it changes.<br>
- string name
+
'''Response:'''
- int? source
+
* '''Code:''' <code>200 OK</code>
- int user_id
+
* '''Requires key''': <code>true</code>
  
=== Airline Routes ===
+
'''Response data:'''
Retourneert de actieve Airline Pilot-routes op de server
+
The response is a JSON object containing weather data.
 +
<pre>
 +
{
 +
  "time_remaining": 1497, // Time in seconds until next weather change
 +
  "current_weather": "drizzling" // The current weather on the server
 +
}
 +
</pre>
 +
==== <code>GET /forecast.json</code> ====
 +
Fetches info about the current forecast on the server.<br>
 +
'''Response:'''
 +
* '''Code:''' <code>200 OK</code>
 +
* '''Requires key''': <code>true</code>
  
GET /status/airline.json
+
'''Response data:'''
object
+
The response is a JSON object containing forecast data.
- object[string player] player
+
<pre>
-- string plane
+
[
-- object destination
+
  'CLEAR',      'OVERCAST',
--- float x
+
  'EXTRASUNNY', 'CLEARING',
--- float y
+
  'RAIN',      'RAIN',
--- float z
+
  'RAIN',      'CLOUDS',
--- float h
+
  'FOGGY'
--- string airport
+
]
--- string name
+
</pre>
-- bool atTerminal
+
==== <code>GET /airline.json</code> ====
 +
Returns the current active destinations for players doing airline.<br>
 +
'''Response:'''
 +
* '''Code:''' <code>200 OK</code>
 +
* '''Requires key''': <code>true</code>
  
=== Krijg resourceconfiguraties ===
+
'''Response data:'''
Dit kan worden gebruikt om gemakkelijk vectorgegevens voor routes enz. In bepaalde banen te krijgen
+
<pre>
Niet alle bronnen hebben zichtbare configuraties
+
{
 +
  "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
 +
  ]
 +
}
 +
</pre>
  
GET /status/config/[resource]
+
==== <code>GET /players.json</code> ====
returns a raw .lua file dump
+
Fetches basic data about the current players on the server.<br>
 +
'''Response:'''
 +
* '''Code:''' <code>200 OK</code>
 +
* '''Requires key''': <code>false</code>
  
=== Top10 Statistieken ===
+
'''Response data:'''
Retourneert een lijst met de top 10 voor de stat in aflopende volgorde.<br>
+
<pre>
Notitie: Gebruikersnamen zijn nogal onbetrouwbaar, dus de kans is groot dat ze een verkeerde indeling hebben of ongeldige tekens bevatten.
+
{
 +
  "players": [
 +
    [
 +
      "xxxx", // [0] user name
 +
      895, //    [1] source id
 +
      41306 //  [2] vRP id
 +
    ],
 +
  ]
 +
}
 +
</pre>
  
Enkele geldige statistieken:<br>
+
==== <code>GET /map/positions.json</code> ====
firefighter_streak_record<br>
+
Fetches the data of players, including position and vehicle data, along with each player's last 20 locations separated by around 4 seconds.<br>
omni_void_leaderboard<br>
+
'''Note: the position history doesn't seem to apply to every player, so make sure to check if this data exists first!'''<br>
ems_streak_record<br>
+
'''Response:'''
houses_crafted<br>
+
* '''Code:''' <code>200 OK</code>
toll_paid<br>
+
* '''Requires key''': <code>true</code>
 +
 
 +
'''Response data:'''
 +
<pre>{
 +
  "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
 +
}</pre>
 +
 
 +
==== <code>GET /widget/players.json</code> ====
 +
Fetches basic data about the current players on the server.<br>
 +
'''Response:'''
 +
* '''Code:''' <code>200 OK</code>
 +
* '''Requires key''': <code>false</code>
 +
 
 +
'''Response data:'''
 +
<pre>
 +
{
 +
  "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
 +
    ]
 +
  ]
 +
}
 +
</pre>
 +
 
 +
<hr></hr>
 +
 
 +
=== 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.
 +
 
 +
==== <code>GET /top10/[statName]</code> ====
 +
Fetches the top 10 info for the specific stat. Available stats:<br>
 +
<pre>
 +
firefighter_streak_record
 +
omni_void_leaderboard
 +
ems_streak_record
 +
ems_deliveries
 +
houses_crafted
 +
toll_paid
 +
trap_paid
 
drops_collected
 
drops_collected
 +
quarry_excavate
 +
quarry_coop
 +
quarry_deliver
 +
quarry_solo
 +
vehicles_crafted
 +
eastereggs_pickup
 +
maid_maxscans
 +
maid_ticket
 +
</pre>
 +
'''Response:'''
 +
* '''Code:''' <code>200 OK</code>
 +
* '''Requires key''': <code>true</code>
 +
 +
'''Response data:'''
 +
<pre>
 +
{
 +
  "code": "200",
 +
  "stat": "toll_paid",
 +
  "top": [
 +
    {
 +
      "amount": 14765137,
 +
      "username": "xxxxx",
 +
      "user_id": 41306
 +
    },
 +
    ...
 +
  ]
 +
}
 +
</pre>
 +
 +
==== <code>GET /config/[resourceName]</code> ====
 +
Pulls the config.lua of specific server resources which support this. Available resources:
 +
{|class="article-table  sortable" style="width: 100%;"
 +
|-
 +
! data-sort-type="text" style="width: 20%" |'''Type/Job'''
 +
! data-sort-type="text" style="width: 80%" |'''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:''' <code>200 OK</code>
 +
* '''Requires key''': <code>false</code>
 +
 +
'''Response data:'''
 +
The lua file which configures the given resource.
 +
<pre>
 +
--[[ 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)
 +
      },
 +
  }
 +
  ...
 +
</pre>
 +
 +
==== <code>GET /snowflake2user/[discordId]</code> ====
 +
Converts the discord snowflake into a vRP id, for use in other endpoints.<br>
 +
'''Response:'''
 +
* '''Code:''' <code>200 OK</code>
 +
* '''Requires key''': <code>true</code>
 +
 +
'''Response data:'''
 +
<pre>
 +
{
 +
  "code": "200",
 +
  "user_id": 41306,
 +
  "discord_id": 138725221749358592,
 +
  "type": "linked"
 +
}
 +
</pre>
 +
 +
 +
==== <code>GET /getuserbiz/[vRPid]</code> ====
 +
Get users owned businesses.<br>
 +
'''Response:'''
 +
* '''Code:''' <code>200 OK</code>
 +
* '''Requires key''': <code>true</code>
 +
 +
'''Response data:'''
 +
<pre>
 +
{
 +
  "code": "200",
 +
  "businesses": {
 +
    "biz_vespucci_masks": 14 // [id]: level
 +
  },
 +
  "user_id": 41306
 +
}
 +
</pre>
 +
 +
==== <code>GET /ownedvehicles/[vRPid]</code> ====
 +
Get users owned vehicles.<br>
 +
'''Response:'''
 +
* '''Code:''' <code>200 OK</code>
 +
* '''Requires key''': <code>true</code>
 +
 +
'''Response data:'''
 +
<pre>
 +
{
 +
  "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
 +
}
 +
</pre>
 +
 +
==== <code>GET /data/[vRPid]</code> ====
 +
Get users data, such as inventory, clothing, and more.<br>
 +
'''Response:'''
 +
* '''Code:''' <code>200 OK</code>
 +
* '''Requires key''': <code>true</code>
 +
 +
'''Response data:'''
 +
<pre>
 +
{ // 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
 +
      }
 +
    }
 +
  }
 +
  ...
 +
}
 +
</pre>
 +
 +
==== <code>GET /dataadv/[vRPid]</code> ====
 +
Get users data with more detailed item info (weight, name, etc).<br>
 +
'''Response:'''
 +
* '''Code:''' <code>200 OK</code>
 +
* '''Requires key''': <code>true</code>
 +
 +
'''Response data:'''
 +
<pre>
 +
{
 +
  "amount": 185,
 +
  "weight": 0.0,
 +
  "name": "<span style=\"color:lawngreen\">Sandwich</span>"
 +
},
 +
</pre>
 +
 +
==== <code>GET /chest/[chestName]</code> ====
 +
Allows you to fetch the items inside of chests.<br>
 +
'''Chest naming scheme cheatsheat:'''
 +
* Fetch vehicle storage: <code>u[vRPid]veh_[vehClass]_[model]</code>
 +
* Fetch home storage: <code>u[vRPid]home</code>
 +
* Fetch backpack storage: <code>u[vRPid]backpack</code>
 +
* Fetch faction storage: <code>self_storage:[vRPid]:faq_[factionId]:chest</code>
 +
* Other storage: <code>self_storage:[vRPid]:[storageId]:chest</code>
 +
 +
'''Response:'''
 +
* '''Code:''' <code>200 OK</code>
 +
* '''Requires key''': <code>true</code>
 +
 +
'''Response data:'''
 +
<pre>
 +
{
 +
  "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"
 +
}
 +
</pre>
 +
 +
==== <code>GET /wealth/[vRPid]</code> ====
 +
Returns users wealth
 +
 +
'''Note: User Must be online to obtain wealth Data'''
 +
 +
'''Response:'''
 +
* '''Code:''' <code>200 OK</code>
 +
* '''Requires key''': <code>true</code>
 +
'''Response data:'''
 +
<pre>
 +
{
 +
  "user_id": 256983,
 +
  "wallet": 101256983,
 +
  "bank": 0,
 +
  "loan": 0,
 +
  "code": "200"
 +
}
 +
</pre>
 +
 +
<hr></hr>
 +
 +
=== 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.<br>
 +
Do note, all endpoints except <code>GET /getuserfaq/[vRPid]</code> are related to the faction the key creator is in and may require a certain rank in the faction.
 +
 +
==== <code>GET /getuserfaq/[vRPid]</code> ====
 +
Returns the faction the user is in, if in any.<br>
 +
 +
'''Response:'''
 +
* '''Code:''' <code>200 OK</code>
 +
* '''Requires key''': <code>true</code>
 +
 +
'''Response data:'''
 +
<pre>
 +
{
 +
    "is_in_faction": true,
 +
    "faction_id": 56,
 +
    "code": "200",
 +
    "user_id": xxxxx
 +
}
 +
</pre>
 +
 +
==== <code>GET /faction/size.json</code> ====
 +
Returns the amount of members in faction.<br>
 +
 +
'''Response:'''
 +
* '''Code:''' <code>200 OK</code>
 +
* '''Requires key''': <code>true</code>
 +
 +
'''Response data:'''
 +
<pre>
 +
[787] // 0: Member count
 +
</pre>
 +
 +
==== <code>GET /faction/members.json</code> ====
 +
Returns the info of the members in a faction.<br>
 +
 +
'''Response:'''
 +
* '''Code:''' <code>200 OK</code>
 +
* '''Requires key''': <code>true</code>
 +
 +
'''Response data:'''
 +
<pre>
 +
  { // 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
 +
  }
 +
]
 +
</pre>
 +
 +
==== <code>GET /faction/perks.json</code>  ====
 +
Returns the amount of perks a faction has<br>
 +
 +
'''Response:'''
 +
* '''Code:''' <code>200 OK</code>
 +
* '''Requires key''': <code>true</code>
 +
 +
'''Response data:'''
 +
<pre>
 +
[39] // 0: Perk amount
 +
</pre>
 +
 +
==== <code>GET /faction/balance.json</code> ====
 +
Returns the factions balance<br>
 +
 +
'''Response:'''
 +
* '''Code:''' <code>200 OK</code>
 +
* '''Requires key''': <code>true</code>
 +
 +
'''Response data:'''
 +
<pre>
 +
[107965.0] // 0: Faction balance
 +
</pre>
 +
 +
==== <code>GET /faction/info.json</code> ====
 +
Returns some basic faction info<br>
 +
 +
'''Response:'''
 +
* '''Code:''' <code>200 OK</code>
 +
* '''Requires key''': <code>true</code>
 +
 +
'''Response data:'''
 +
<pre>
 +
{
 +
  "tag": "The Corrupt",
 +
  "faction_id": 56,
 +
  "name": "CoCo"
 +
}
 +
</pre>
 +
 +
<hr></hr>
 +
 +
=== [LITE] endpoints ===
 +
These endpoints are specific to the [LITE] Transportation server and are not shared with the main Transport Tycoon servers.
 +
 +
==== <code>GET sessionmanager/players.json</code> ====
 +
Returns a list of players, similar to the main servers' <code>status/widget/players.json</code>.
 +
 +
'''Response:'''
 +
* '''Code:''' <code>200 OK</code>
 +
* '''Requires key''': <code>false</code>
  
GET /status/top10/[stat]
+
'''Response data:'''
object
+
<pre>
-array top
+
{
-- int user_id
+
  "server": {
-- string user_name
+
    "number": "",
-- int stat_count
+
    "dxp": [false],
[[Category:Development]]
+
    "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
 +
    ],
 +
    ...
 +
  ]
 +
}
 +
</pre>

Revision as of 02:02, 15 September 2021

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.

Privacy related options

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 billionaires, etc.
Response:

  • Code: 200 OK
  • Requires 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

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, including 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 each player's last 20 locations separated by around 4 seconds.
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 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]

Returns users wealth

Note: User Must be online to obtain wealth Data

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
    ],
    ...
  ]
}