Difference between revisions of "API"
m (add warning about positions.json data) |
m (specify the missing data originates from position history and not just blanket positions.json) |
||
Line 180: | Line 180: | ||
==== <code>GET /map/positions.json</code> ==== | ==== <code>GET /map/positions.json</code> ==== | ||
Fetches the data of players, including position and vehicle data, along with the players last 20 locations, which is about ~4 seconds of data.<br> | Fetches the data of players, including position and vehicle data, along with the players last 20 locations, which is about ~4 seconds of data.<br> | ||
− | '''Note: | + | '''Note: the position history doesnt seem to apply to every player, so make sure to check if this data exists first!'''<br> |
'''Response:''' | '''Response:''' | ||
* '''Code:''' <code>200 OK</code> | * '''Code:''' <code>200 OK</code> |
Revision as of 19:59, 10 February 2021
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
Address | Server Name | Additional Information |
---|---|---|
server.tycoon.community:30120 | Server 1 | OneSync server, may not be as stable as the other servers |
server.tycoon.community:30122 | Server 2 | |
server.tycoon.community:30123 | Server 3 | |
server.tycoon.community:30124 | Server 4 | |
server.tycoon.community:30125 | Server 5 | Beta server, data could end up being different compared to other servers |
na.tycoon.community:30120 | Server 6 | Despite the na subdomain, these servers are not hosted in NA, and are also European |
na.tycoon.community:30122 | Server 7 | |
na.tycoon.community:30123 | Server 8 | |
na.tycoon.community:30124 | Server 9 | |
na.tycoon.community:30125 | Server 10 |
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 is 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 users 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 takes 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.
As the API has been more and more commonly used, it is now possible to restrict this data, meaning that only your API key will have access to your personal data. In order to restrict access, do /api lock
in-game, which will enable these features.
API Endpoints
General notes
- API keys should be sent as headers, like such:
X-Tycoon-Key: [api-key]
- Each endpoint here will mention if such a key is required to be used.
- Typically, this data is returned as JSON, unless explicity mentioned.
- Most routes will have a response header called
X-Tycoon-Charges
, which will give you the amount 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
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 /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 27576791, // Time remaining 0 // Extra DXP time ], "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 ] ] }
GET /advanced/
Returns data about the users in HTML format, will need to be parsed for any sort of use.
Response:
- Code:
200 OK
- Requires key:
false
Global endpoints
These endpoints should return data regardless of the server they are run on (excluding beta for obvious reasons). 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:
es_bus omni_pax omni_postop_ground omni_businesses omni_paramedic omni_self_storage omni_garbage omni_helitour omni_postop_air
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 /inventory/[vRPid]
Get users inventory formatted as HTML.
Response:
- Code:
200 OK
- Requires key:
true
GET /skills/[vRPid]
Get users inventory formatted as HTML.
Response:
- Code:
200 OK
- Requires key:
true
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.
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 backback 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" }