World API

vMenu decides what the sky is doing. It picks the weather, it runs the clock, and it works out the date and the moon phase from that clock. All of that lives inside the game, which is a problem the moment you want something outside the game to know about it. A Discord bot that posts “rain in twenty minutes”, a website that shows the in-game time, a companion app that says whether tonight is a full moon: none of them can see any of it.

The World API is a small web address on your server that answers exactly that question. You ask it, and it hands back a single block of data describing the time, the date, the moon, the current weather and what is coming next.

It only ever reads. Nothing you send to it can change the weather, the time, or anything else.

Switching it on

The endpoint is off until you give it a password. That password is called a token, and it is just a long piece of random text that only you and your tools know.

Add this to your server config, replacing the text between the quotes with your own random string:

set vMenu.Enhanced.WorldApi.Token "a-long-random-string-nobody-can-guess"

Then restart the resource.

Leave the token empty, or leave the line out entirely, and the endpoint answers every request with a polite refusal instead. That is the default.

Where it lives

http://your-server-address:30120/vMenu.Enhanced/world

It runs on the same port your game server already uses, so there is nothing new to open in your firewall and nothing new to forward on your router. 30120 is the usual FiveM port. If you changed yours, use that number instead.

Asking it something

Send the token in a header called X-vMenu-Token:

curl -H "X-vMenu-Token: a-long-random-string-nobody-can-guess" \
  http://your-server-address:30120/vMenu.Enhanced/world

Some tools make headers awkward. If yours is one of them, you can put the token in the address instead:

curl "http://your-server-address:30120/vMenu.Enhanced/world?token=a-long-random-string-nobody-can-guess"

The header is the better of the two, because addresses tend to end up written down in logs and browser history while headers usually do not.

Asking for a longer forecast

By default you get the next 10 weather changes. Add forecast to the address to ask for a different number, anywhere from 0 to 48:

http://your-server-address:30120/vMenu.Enhanced/world?forecast=24

What comes back

A block of JSON, which is a plain text format that essentially every programming language can read without any extra work. It looks like this:

{
  "utc": 1756800000,
  "sync": { "weather": true, "time": true },
  "clock": {
    "speed": 1.0,
    "frozen": false,
    "frozenAtUnix": null,
    "offsetSeconds": 0,
    "secondOfDay": 43200,
    "hour": 12,
    "minute": 0,
    "second": 0,
    "realSecondsPerGameHour": 120.0
  },
  "date": {
    "dayOfLoop": 12,
    "loopDays": 385,
    "year": 2000,
    "month": 1,
    "day": 13,
    "weekday": "Thursday"
  },
  "moon": {
    "dayOfCycle": 12.5,
    "cycleDays": 55.0,
    "phase": "waxing crescent",
    "illumination": 0.43,
    "angleDegrees": -95.4
  },
  "weather": {
    "override": null,
    "scheduled": "EXTRASUNNY",
    "current": "EXTRASUNNY",
    "next": "CLOUDS",
    "gameHoursUntilNext": 2.5,
    "realSecondsUntilNext": 300.0,
    "cycleGameHours": 123.45,
    "cycleLengthGameHours": 384.0,
    "cycle": "default",
    "cycleMode": "default",
    "cycleEntries": [
      { "gameHour": 0.0, "type": "EXTRASUNNY" },
      { "gameHour": 2.0, "type": "CLEAR" }
    ],
    "snowPass": false,
    "blackout": "off",
    "blackoutMode": "dynamic",
    "snow": "auto",
    "snowFalling": false,
    "temperatureCelsius": 30.0,
    "temperatureFahrenheit": 86.0
  },
  "forecast": [
    {
      "type": "CLOUDS",
      "gameHoursUntilStart": 2.5,
      "realSecondsUntilStart": 300.0,
      "gameHoursLong": 4.0,
      "realSecondsLong": 480.0
    }
  ],
  "temperatureOutlook": [
    {
      "gameHoursAhead": 0.75,
      "realSecondsAhead": 90.0,
      "hour": 13,
      "minute": 0,
      "weather": "EXTRASUNNY",
      "celsius": 31.3,
      "fahrenheit": 88.3
    }
  ],
  "temperatures": {
    "sampleHours": [0, 5, 6, 7, 10, 12, 16, 17, 18, 19, 20, 21, 22],
    "sampleHolds": [4, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
    "rows": [
      { "type": "CLEAR", "celsius": [14.5, 14, 14, 16, 19.5, 27, 31, 31.5, 23, 19, 15, 14, 14.5] }
    ]
  }
}

The top level

Field	What it means
`utc`	The server’s own clock, as the number of seconds since the 1st of January 1970. That is the standard way computers write a moment in time, and every language has a way to turn it back into a date.
`sync`	Whether vMenu is actually in charge. If `weather` is `false` something else on your server is driving the sky, and the weather below is what vMenu would be showing rather than what players are seeing. Same idea for `time`.

`clock`

Field	What it means
`speed`	How much faster than normal the in-game clock runs. `1.0` is the game’s own pace.
`frozen`	Whether somebody has stopped the clock from the menu.
`frozenAtUnix`	The moment it was stopped, or `null` when it is running.
`offsetSeconds`	How far the in-game clock has been nudged away from where the schedule would put it.
`secondOfDay`	How far through the in-game day it is, in seconds, from `0` at midnight to `86400`.
`hour`, `minute`, `second`	The same thing, split up, so you can print it without doing any sums.
`realSecondsPerGameHour`	How many real seconds one in-game hour takes at the current speed. `120` at normal speed, so a full in-game day takes 48 real minutes.

`date`

The in-game calendar. GTA does not really have one, so vMenu keeps its own: a 385 day loop that always leaves the weekday and the moon phase lining up when it wraps around.

Field	What it means
`dayOfLoop`	Which day of that loop it is.
`loopDays`	How long the loop is, always `385`.
`year`, `month`, `day`	The date those days work out to.
`weekday`	The day of the week, written out.

`moon`

Field	What it means
`dayOfCycle`	How far through the moon’s cycle it is, in days.
`cycleDays`	How long that cycle is, always `55` in-game days.
`phase`	The phase written out, such as `full moon` or `waning gibbous`.
`illumination`	How much of the moon is lit, from `0` at new moon to `1` at full.
`angleDegrees`	The angle the game tilts the moon by, if you want to draw it yourself. `0` is a full moon.

`weather`

Field	What it means
`override`	The weather somebody forced from the menu, or `null` when the schedule is running normally.
`scheduled`	What the schedule says the weather is, whether or not anybody has overridden it.
`current`	What players are actually seeing. The override if there is one, otherwise the scheduled weather. This is the one to show people.
`next`	The weather the schedule moves to next.
`gameHoursUntilNext`	How many in-game hours away that change is.
`realSecondsUntilNext`	How many real seconds away it is, which already accounts for the clock speed. This is the one to count down with.
`cycleGameHours`	How far through the weather schedule the server is.
`cycleLengthGameHours`	How long the whole schedule is in in-game hours. `384` for the default schedule, `180` for the snowy one, and whatever the blocks add up to for a custom one.
`cycle`	Which weather schedule the server runs: `default` for the GTA Online one, `snowy` for the winter one, or `custom` for the server’s own weather-cycle.json. This follows `vMenu.Enhanced.WeatherOptions.WeatherCycle`, except that a custom schedule that could not be loaded shows up as `default`, because that is what the server falls back to.
`cycleMode`	The weather schedule setting itself: `default`, `snowy` or `custom`. Differs from `cycle` only when a custom schedule could not be loaded.
`cycleEntries`	The whole schedule that `cycle` names, in order. Each entry is the in-game hour a block starts at, counted from the start of the schedule, and the weather it has. A block lasts until the next entry starts, and the last one lasts until the schedule starts over. This lets you work out the forecast yourself, far beyond what `forecast` lists. An entry from a custom schedule can also have a `blackout` (`city` or `all`), which is the blackout planned for that block. Entries without one have no `blackout` field at all.
`snowPass`	Whether the schedule keeps snow on the ground the whole time while `snow` is `auto`. Always `true` for the snowy schedule, and whatever the server owner picked for a custom one.
`blackout`	Whether street lighting is cut right now: `off`, `city`, or `all`.
`blackoutMode`	The blackout setting: `dynamic` (follow the blackouts scheduled in a custom weather schedule, the default), `off`, `city`, or `all`.
`snow`	The snow setting: `auto`, `on`, or `off`.
`snowFalling`	Whether that setting works out to snow actually falling right now.
`temperatureCelsius`	How warm it is outside right now, in degrees Celsius. See temperatures below for where this number comes from.
`temperatureFahrenheit`	The same temperature in degrees Fahrenheit, so you do not have to convert it yourself.

`forecast`

A list of the weather changes still to come, in order. Each entry says what the weather turns into, how long until it starts, and how long it lasts. Every one of those is given twice, once in in-game hours and once in real seconds, so you never have to do the clock speed maths yourself.

`temperatureOutlook`

A rough temperature for each of the next 48 whole in-game hours, so you can draw a little temperature chart or say “it will be cold tonight”. The entries always land exactly on the hour, so at 14:20 the first one is 15:00, the next one 16:00, and so on. Once the clock passes 15:00, that entry drops off the front and a new one appears at the end.

Field	What it means
`gameHoursAhead`	How many in-game hours from now this entry is. The first one is less than an hour away.
`realSecondsAhead`	The same distance in real seconds, which already accounts for the clock speed.
`hour`, `minute`	What the in-game clock will show at that moment.
`weather`	The weather the schedule will be on at that moment. If somebody forced a weather type from the menu, this assumes it stays forced.
`celsius`, `fahrenheit`	The temperature at that moment, in both units.

`temperatures`

The table every temperature on this page is worked out from, for the weather schedule the server is running right now. Use it if you want to show temperatures further ahead than temperatureOutlook goes, together with cycleEntries.

Field	What it means
`sampleHours`	The in-game hours of the day the table has a temperature for.
`sampleHolds`	How many in-game hours each sample stays put before it starts sliding towards the next one. Only midnight holds, until 04:00.
`rows`	One row for every weather type: its name in `type`, and in `celsius` its temperature at each of the `sampleHours`, in the same order. Between two samples the temperature slides evenly from one to the next.

Temperatures

GTA works out a temperature for its world all the time, it just never shows it to anyone. vMenu works out its own version of it. Every weather type has its own temperature for each part of the day, so a sunny afternoon is hot and a rainy night is chilly. While the weather is changing from one type to another, the temperature slides between the two.

A few things to know about these numbers:

They are the temperature outside, at sea level. Players high up in the hills or flying feel it colder, because the game drops the temperature by up to 15°C between 200 and 1000 metres up. The forecast on a player’s screen does take their height into account. This endpoint cannot, because it does not know where anybody is standing.
They are the weather temperature, not the temperature inside a building.
The game’s own data for a couple of the snowy weather types was clearly typed in wrong (it had a snowy noon at 20°C, for example). vMenu smooths those out to sensible values.
While the snowy weather schedule is on, or a custom one with snowPass turned on, every weather type switches to its own winter temperatures. A foggy or cloudy day in the middle of winter is still freezing.

When something goes wrong

Code	What happened
`401`	The token was missing or wrong.
`404`	The address was not `/world`.
`405`	You used something other than a `GET` request.
`503`	The endpoint is switched off, because `vMenu.Enhanced.WorldApi.Token` is empty.

Wrong tokens are noted in your server console, at most one line every ten seconds so somebody poking at it cannot bury everything else.