Lumaha Virtual Balloon Race

A balloon race without the balloons: no litter, no harm to wildlife, and supporters can follow their balloon live. Virtual Balloon Race is made for schools, PTAs, clubs and charities.

Supporters buy an entry in your WooCommerce shop, name their balloon, choose its colour and helium strategy, and can add their own logo or launch point. When the race launches, every balloon drifts across a live map on real wind data, and a leaderboard ranks them by how far they get from the launch point.

For supporters

• A live preview of their balloon on the product page as they choose its colour, name, team and logo
• A live map with each balloon’s trail; tap a balloon to follow it
• A leaderboard with search and paging, team standings, and “My balloons” for logged-in entrants
• Emails when the race launches and when it finishes, with each balloon’s final position
• My Account → My balloons, and “Track your balloon” links on order pages and emails

For organisers

• Schedule races: entries open, launch, end; or press Launch now / Finish now on the day
• A tracking page and a ready-to-sell “Balloon Race Entry” product are created for you
• Paid extras: tactical helium strategy, custom launch point, logo upload
• Optional teams (e.g. houses or classes), scored by average, total or best distance
• Optional entry limits, with “Only N places left!” and “Sold out” in the shop
• Three flight modes: Drift (true to life), Soar (the default) and Jetstream (maximum distance)
• Refunded, cancelled or failed orders take their balloons out of the race automatically
• Withdraw or reinstate balloons by hand, mark bursts, advance the race, export a CSV
• Public names are shown as first name and last initial

The map uses Leaflet (bundled with the plugin) and OpenStreetMap. Wind comes from Open-Meteo. No API keys are needed; busier or commercial sites can add keys for paid map and weather providers. See External services below.

External services

This plugin can connect to the third-party services below. Nothing is contacted until the site admin allows it: on a new site, external services are off, and the plugin’s admin screens ask once whether to allow them (or tick Allow external services in Balloon Race → Settings → Maps, weather and place search). Until then, maps show the balloons without a background map, balloons follow the default heading instead of the live wind, and place search is hidden. The free services need no API keys or accounts; the same Settings section can switch to keyed providers for busier or commercial sites.

Sponsor views and clicks are only counted if the site admin turns it on (Settings → Data). They are counted by your own site (totals only, no cookies, IP addresses or other visitor data), and nothing is sent to any other service.

Open-Meteo (weather)

Used to move balloons with the real wind. When a race is flying, your server requests the current wind speed and direction for the areas the balloons are in (rounded latitude and longitude) each time balloons move. No personal data is sent; requests identify only the plugin and its version. With an Open-Meteo API key set, requests go to customer-api.open-meteo.com and include the key.
Service: open-meteo.com. Terms of use. The free API is for non-commercial use; for commercial use, get an API key.

Map tiles: OpenStreetMap, MapTiler, Stadia Maps or a custom provider

Used to draw the map. Visitors’ browsers load map images from the chosen provider whenever a map is shown (public race map, Settings, race screen, and the launch point picker on the product page), which shares their IP address and browser details with that provider. With a keyed provider, the key is part of each image address.

• OpenStreetMap (default): tile.openstreetmap.org. Tile usage policy. Privacy policy.
• MapTiler (optional): api.maptiler.com. Terms. Privacy policy.
• Stadia Maps (optional): tiles.stadiamaps.com. Terms. Privacy policy.
• Custom: whatever tile address the site admin enters.

Place search: Nominatim or MapTiler

Used by the “search for a place” box when choosing a launch point (in Settings, on the race screen, and for buyers choosing a custom launch point). When the Search button is pressed, the text typed is sent from the visitor’s browser to the chosen service (at most one search a second). Place search can be switched off.

• Nominatim (default): nominatim.openstreetmap.org. Usage policy. Privacy policy.
• MapTiler (optional, with MapTiler map tiles): api.maptiler.com. Terms. Privacy policy.