Nearest-postal scripts: how they work and how to match your map

#How a postal script works

The best-known open-source implementation, DevBlocky’s nearest-postal, set the pattern most others follow: a JSON file of postal points, a client loop that finds the closest point, a text element drawn near the minimap, and a command to route to a code.

[
  { "code": "7042", "x": 215.8, "y": -810.1 },
  { "code": "7043", "x": 290.4, "y": -825.0 },
  { "code": "7044", "x": 372.1, "y": -835.6 }
]

Each point marks the centre (or a representative spot) of one postal area. “Nearest postal” is simply the point with the smallest distance to the player.

#The postal file must match your map

There is no single official postal grid for GTA V. Several community grids exist, and each postal map texture prints one of them. If the map shows 7042 on a block and the script says 312 when you stand there, players stop trusting both.

• Get the postal JSON from the same source as your postal map, or confirm they use the same grid.
• Stand on three or four postal numbers printed on the pause map and check the script agrees.
• If you switch maps, switch postal files at the same time.

How baked postal maps work — and why some servers skip the script entirely — is covered in postal codes explained.

#Showing the nearest postal

local postals = json.decode(LoadResourceFile(GetCurrentResourceName(), 'postals.json'))
local nearest = nil

CreateThread(function()
    while true do
        local pos = GetEntityCoords(PlayerPedId())
        local best, bestDist = nil, math.huge
        for i = 1, #postals do
            local p = postals[i]
            local dx, dy = pos.x - p.x, pos.y - p.y
            local d = dx * dx + dy * dy -- squared distance: no sqrt needed
            if d < bestDist then best, bestDist = p, d end
        end
        nearest = best
        Wait(1000)
    end
end)

Comparing squared distances avoids a square root per point; with a few thousand points that loop is trivial once a second. Draw nearest.code with your HUD, or send it to an NUI HUD only when it changes. Remember to add postals.json to files in the manifest.

#The /postal command

local byCode = {}
for _, p in ipairs(postals) do byCode[p.code] = p end

RegisterCommand('postal', function(_, args)
    local code = args[1]
    if not code then
        SetWaypointOff()
        return
    end
    local p = byCode[code]
    if not p then return print('unknown postal ' .. code) end
    SetNewWaypoint(p.x, p.y)
end, false)

A lookup table keyed by code makes the command instant. Waypoints are explained in the pause menu map guide.

#Dispatch and 911 integration

Dispatch alerts, 911 calls and MDTs are much more useful with a postal attached. Expose the nearest postal through an export (for example exports.my_postal:getPostal()) and have those scripts call it, so every system uses one source. How resources talk to each other is covered on pityus.net in FiveM events explained.