# Looper backup format

A Looper backup is one person's whole drive log in a single file. Looper makes one with **Download a backup**, and takes one back with **Import a backup** on the Profile page. Anyone can build a file in this format from other records (a club's spreadsheet, another app) and import it into a Looper account.

## The file

A gzipped tar file, `something.tar.gz`, with these inside, at the top level (no folder around them):

| Path | What it is | Needed |
|---|---|---|
| `drives.json` | Every drive | Yes |
| `drivers.json` | Every driver who appears on a drive, with their cars and levels | Yes (can be `{}`) |
| `profile.json` | Whose drive log it is | Yes |
| `gaia-tracks.json` | Gaia GPS track ids by drive (only for drives made from Gaia) | No |
| `tracks/<Trip ID>.gpx` | A drive's GPS track (GPX 1.1, with times on the points) | No, but each drive's report, map, speed chart and weather come from it |
| `photos/<Trip ID>/<n>.jpg` and `<n>_t.jpg` | A drive's photos, full size and a small thumbnail | No |

All text is UTF-8. Dates are `YYYY-MM-DD`; times are `HH:MM`, 24-hour, local time (UAE). Anything not listed below is ignored. A field can be left out or `null` when it isn't known.

## profile.json

```json
{ "carnityName": "Bert", "clubs": ["Dune Raiders"], "mode": "convoy" }
```

| Field | Meaning |
|---|---|
| `carnityName` | **The owner's name as their clubs know them.** It must be the same as their `name` in the convoys and their key in `drivers.json`: that is how Looper knows which car is theirs. |
| `clubs` | The clubs they drive with, by name (e.g. `"Carnity"`, `"AD4x4"`, `"Dune Raiders"`). A club not on Looper's list is kept as written. |
| `mode` | `"convoy"` (drives with their convoys) or `"solo"` (just my drive: the log shows only the owner's own car and figures). |

The account's username and email are not in the file: an import keeps the account's own.

## drives.json

An object with one entry per drive, keyed by its **Trip ID**: 2 to 20 letters, digits, `-` or `_`, e.g. `"NB0001"`. The same Trip ID names its track and photo folder.

```json
{
  "NB0001": {
    "date": "2026-10-31", "slot": "Afternoon", "time": "15:30", "finish": "18:15",
    "location": "Badayer", "club": "Dune Raiders", "level": "Newbie", "status": "Done",
    "title": "Afternoon Newbie Drive", "tagline": "Season opening convoy",
    "lead": "Bert", "host": "Bert", "ordered": true,
    "convoy": [
      { "name": "Bert", "role": "Lead", "level": "Marshal", "make": "Toyota", "model": "FJ Cruiser", "colour": "Black" },
      { "name": "Krishna", "level": "Intermediate" },
      { "name": "Cezar", "role": "Sweep" }
    ],
    "stops": [ { "from": "16:32", "to": "16:54", "reason": "Break", "note": "Tea break" } ],
    "photos": [ { "file": "photos/NB0001/1.jpg", "thumb": "photos/NB0001/1_t.jpg", "caption": "The start", "takenAt": "2026-10-31T15:31:00", "lat": 24.9553, "lon": 55.7158 } ],
    "gaia": "https://www.gaiagps.com/public/…"
  }
}
```

| Field | Meaning |
|---|---|
| `date` | The day of the drive. **Needed.** |
| `slot` | `Morning`, `Afternoon`, `Evening`, `Night` or `All Day` |
| `time`, `finish` | Meeting time and back time, `HH:MM` |
| `location` | The place, e.g. `"Al Qudra, Dubai"` |
| `club` | The club the drive was with, or `"Personal"` for a drive on your own |
| `level` | The drive's level as the club names it (e.g. `"Newbie"`, `"Fewbie"`) |
| `status` | `Done`, `Planned` or `Cancelled`. A drive with a track counts as done. |
| `title`, `tagline` | The drive's name and one sentence about it |
| `lead`, `host` | Who led, and who posted it (driver names) |
| `solo` | `true` for a drive of the owner's own (then `convoy` holds just the owner, and `lead` is a name only) |
| `ordered` | `true` when the convoy is in driving order, lead first |
| `convoy` | The cars, in order: see below |
| `myLevel`, `myRole` | The owner's level and role (`Lead`, `Support`, `Attend`) on the drive, only when the owner isn't in an ordered convoy |
| `stops` | Events: see below |
| `photos` | See below |
| `gaia` | A public Gaia GPS link to the track (used when there is no GPX file) |
| `trackLink` | A GPX file shared from Google Drive or Dropbox (the same) |
| `carnity` | The Carnity event link |
| `radio` | The radio channel, by its name in the club's list (e.g. `"3"`) |
| `comments` | The owner's own notes for their forum post. Private: never shown to others or exported. |
| `recorded` | For an old drive without a track: `{ "km": 35.9, "totalMin": 125, "movingMin": 105, "movingKmh": 20.5, "convoySize": 11 }` |

**Convoy** entries: `name` (the driver, a key in `drivers.json`; **needed**), `display` (a different name to show), `role` (`Lead`, `Second lead`, `Centre forward`, `Flying sweep` or `Sweep`; several drivers can share one), `level` (their level that day), `first` (`true` on their first drive), and the car that day when it differs from their usual one: `make`, `model`, `generation`, `wheelbase` (`LWB` or `SWB`), `colour`.

**Events** (`stops`): `from` and `to` (`HH:MM`), `reason` (`Break`, `Regroup`, `Briefing`, `Tyre pop-out`, `Puncture`, `Breakdown`, `Refusal`, `Stuck`, `Recovery`, `Photo stop`, `Other`, or `Note` for something said without stopping), `note` (what happened).

**Photos**: `file` and `thumb` (paths in the file, as above), `caption`, `takenAt` (`YYYY-MM-DDTHH:MM:SS`, local), `lat` and `lon` (where it was taken), `with` (the `from` time of the event it belongs to). A thumbnail is about 400 px wide.

## drivers.json

An object with one entry per driver, keyed by the name used in the convoys.

```json
{
  "Krishna": {
    "display": "Krishna",
    "cars": [ { "make": "Toyota", "model": "Land Cruiser", "generation": "200", "colour": "White", "from": "2024-03-01" } ],
    "levels": [ { "level": "Newbie", "club": "Dune Raiders" }, { "level": "Intermediate", "club": "Dune Raiders", "from": "2026-02-10" } ],
    "phone": "+971…"
  }
}
```

| Field | Meaning |
|---|---|
| `display` | The name shown |
| `cars` | Their cars over time: `make`, `model`, `generation`, `wheelbase`, `colour`, and `from` (the date it starts; the first needs none). A drive shows the car they had that day. |
| `levels` | Their levels over time, in each club: `level`, `club`, `from` |
| `phone`, `remarks` | Private to the owner: never shown to others or exported |

Car makes, models and generations are best written as Looper's car list has them (e.g. `Jeep` / `Wrangler` / `JL` / `LWB`); anything else still works and shows the closest drawing. Colours are Looper's names: White, Black, Silver, Grey, Red, Blue, Green, Beige / Sand, Orange, Yellow, Brown, Gold (other names are kept).

## gaia-tracks.json

Only for drives made from Gaia GPS: `{ "<Trip ID>": "<Gaia track id>" }`.

## Importing

- **Import a backup** is on the Profile page (this document is at looper.ae/site/backup-format.md). It takes the file and replaces the drive log with it: drives, drivers, tracks, photos, and the name, clubs and mode from `profile.json`.
- Before replacing anything, Looper keeps a copy of the drive log as it was, on the server.
- The file is checked first, and nothing changes if it doesn't open or a part isn't right (for example a drive without a date, a Trip ID that isn't allowed, or a convoy driver without a name). The answer says what to fix.
- Limits: 300 MB for the whole file.