Difference between revisions of "API"

From Tycoon Gaming
m (→‎Public keys: Keys can be AP Keys)
Line 52: Line 52:
 
The API requires an API Key to access most features.
 
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 <code>/api private 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 private 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 private 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.
+
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 private refill</code> command at the cost of $1000 (in-game money) per charge. Any user can generate an API key; this key is the user's private key. (Make sure you keep it safe!) To generate a key, use the <code>/api private 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 private 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.
 +
 
 +
[[File:Api key guide.png|thumb|A depiction of the public/private key relationship]]
  
 
== Public keys ==
 
== Public keys ==
  
−
Public keys are keys that can be used to access a players account information without needing that player's API key and charges.
+
Public keys are keys that can be used to access a players account information without needing that player's private key and charges.
−
These keys change the target account from the API key's owner to the Public key's owner.
+
 
−
The public key cannot be used as an API key, and only works when passed along-side a valid API key.
+
The public key is not valid by itself and must be included alongside a valid private key
−
The public key can be an API key, and data will be based on this Public 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#Privacy related options|API locks]] in place.
  
 
To generate a public key, use <code>/api public generate</code>
 
To generate a public key, use <code>/api public generate</code>
Line 65: Line 68:
 
== Privacy related options ==
 
== 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 <code>/api lock</code> in game, and privacy will be enabled.
+
You may restrict access to your own data with the <code>/api lock</code> 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 ==
 
== API Endpoints ==

Revision as of 21:34, 22 July 2024

French Dutch



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

API Keys

TL;DR: Create a new 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 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 private refill command at the cost of $1000 (in-game money) per charge. Any user can generate an API key; this key is the user's private key. (Make sure you keep it safe!) To generate a key, use the /api private 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 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.

A depiction of the public/private key relationship

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

Privacy related options

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

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

  • 400 Bad Request - invalid endpoint
  • 401 Unauthorized - An API key is required for the route
  • 402 Payment Required - No API charges remaining
  • 403 Forbidden - Invalid API 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 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"
  },
  ...
}

GET /dealership.json

Fetches data about the current dealership rotation.
Response:

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

Get users vehicle inventories.
Response:

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

Response data: 

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

GET /storages/[vRPid]

Returns users storages

Response:

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

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 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 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
  • 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 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 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 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 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 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 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 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=22324"