Difference between revisions of "API"

From Tycoon Gaming
(Add Stats, Streak, Racing(Tracks/User/Race))
m (Move endpoints endpoint into it's own header)
Line 66: Line 66:
  
 
<hr></hr>
 
<hr></hr>
 +
 +
=== Endpoints List ===
 +
 +
==== <code>GET /endpoints.json</code> ====
 +
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).<br>
 +
'''Response:'''
 +
* '''Code:''' <code>200 OK</code>
 +
* '''Requires key''': <code>true</code>
 +
 +
'''Response data:'''
 +
<pre>
 +
[
 +
  ...
 +
  "/faction/balance.json",
 +
  "/charges.json",
 +
  ...
 +
]
 +
</pre>
  
 
=== Main endpoints ===
 
=== Main endpoints ===
Line 145: Line 163:
  
 
=== Server-specific endpoints ===
 
=== Server-specific endpoints ===
−
 
−
==== <code>GET /endpoints.json</code> ====
 
−
Fetches endpoints on the current server.<br>
 
−
'''Response:'''
 
−
* '''Code:''' <code>200 OK</code>
 
−
* '''Requires key''': <code>true</code>
 
−
 
−
'''Response data:'''
 
−
<pre>
 
−
[
 
−
  ...
 
−
  "/faction/balance.json",
 
−
  "/charges.json",
 
−
  ...
 
−
]
 
−
</pre>
 
  
 
==== <code>GET /weather.json</code> ====
 
==== <code>GET /weather.json</code> ====

Revision as of 00:53, 25 March 2022

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:30120

tycoon-2epova.users.cfx.re

Server 2
server.tycoon.community:30121

tycoon-njyvop.users.cfx.re

Server 5 (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.

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

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 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 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

GET /sotd.json

Fetches the current skill rotation for the servers
Response:

  • Code: 200 OK
  • Requires 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 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"
  },
  ...
}

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 /racing/map/[id]

Fetches the name and blip information about a race.
Response:

  • Code: 200 OK
  • Requires 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
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 /streak/[vRPid]

Get users streak.
Response:

  • Code: 200 OK
  • Requires 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 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 /stats/[vRPid]

Returns users stats

Response:

  • Code: 200 OK
  • Requires key: true

Response data: 

{
  ...
  {
    "stat": "quarry_coop",
    "name": "Contributed Quarry Deliveries",
    "amount": 446
  },
  ...
}

GET /racing/races/[vRPid]

Returns users racing stats

Response:

  • Code: 200 OK
  • Requires 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 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
    ],
    ...
  ]
}
Retrieved from "https://dash.tycoon.community/wiki/index.php?title=API&oldid=11368"