For developers
The Trip Binder file
One ordinary .xlsx that The Trip Binder imports as a whole trip: the trip itself, its cover photo, the roster with contacts and health notes, and the itinerary. If your school website, ticketing system or spreadsheet can write a workbook, it can write one of these.
Where it goes
- New trip → Import a Trip Binder file creates the trip and brings over everything in the workbook in one step.
- Roster → Import roster on an existing trip reads the Roster sheet; the columns arrive pre-mapped and re-imports update travelers in place.
- Schedule → Import Trip Binder file on an existing trip reads the Itinerary sheet and lets you review each stop before it is added.
The workbook
Three sheets, named exactly Roster, Trip and Itinerary. Roster must be the first sheet; the Itinerary sheet is optional. Every cell is plain text — write dates and times as text so a spreadsheet program does not reformat them.
Sheet “Trip”
Key in column A, value in column B, one pair per row, in any order. Keys are matched case-insensitively. Anything else on the sheet is ignored, so it can carry notes for the person opening the file.
| Key | Value |
|---|---|
| Format | Required. Exactly "tripbinder-export/1". Without it the workbook is treated as a plain spreadsheet. |
| Name | The trip name. |
| Destination | Optional. |
| Departure | YYYY-MM-DD or M/D/YYYY. |
| Return | Same. Equal to Departure for a day trip. |
| Cover image | Optional. The path of an image file inside the .xlsx zip, e.g. xl/media/image1.jpeg (JPEG or PNG, under 8 MB). We read the bytes out of the workbook itself — no URL to fetch. |
Sheet “Roster”
A header row, then one row per traveler. Headers are matched by name, case-insensitively, with spaces, underscores and dashes treated alike (“EC1 phone”, “ec_phone_1”). Any column we do not recognize is simply skipped, and the import wizard shows it as “Skip this column”, so extra columns for your own use are fine. Provide at least a name.
| Header | Field | Notes |
|---|---|---|
| First name / Last name | first_name, last_name | Or a single "Name" / "Full name" column, which we split. |
| Middle name | middle_name | Optional. |
| Student ID | student_id | Your own ID for the traveler. Best key for re-imports. |
| Grade | grade | Free text: "10", "Grade 10", "Sophomore". |
| DOB | date_of_birth | YYYY-MM-DD or MM/DD/YYYY. Second key for re-imports (with name). |
| Gender | gender | Optional, free text. |
| Student email | student_email | |
| Parent email | parent_email | The primary guardian; used for guardian invites. |
| Parent name | parent_name | |
| Parent phone | parent_phone | |
| Parent email 2 | parent_email_2 | A second guardian address. |
| Traveler type | traveler_type | "student" (default), "staff" or "adult". |
| Bus | bus_label | Any label: "Bus 1", "Blue". |
| Allergies | allergies | Free text. |
| Medications | medical_conditions | Free text; also matches "Medical conditions". |
| Dietary restrictions | dietary_restrictions | |
| Behavioral notes | behavioral_notes | |
| EC1 name / EC1 relationship / EC1 phone / EC1 alt phone | ec_name_1 … | Emergency contact 1. "Emergency contact 1 phone" works too. |
| EC2 …, EC3 … | ec_name_2 …, ec_name_3 … | Up to three contacts. |
Re-importing the same file updates existing travelers rather than duplicating them, matched on Student ID first, then name plus date of birth, then name alone.
Sheet “Itinerary”
A header row, then one row per stop. Times are wall-clock in the organizer’s timezone.
| Header | Notes |
|---|---|
| Date | YYYY-MM-DD or M/D/YYYY. Required. |
| Start | 24-hour "HH:MM" or "7:00 AM". Leave empty for an all-day entry. |
| End | Same format. Ignored when Start is empty. |
| Title | Required. Words in it pick the color: depart/bus → travel, lunch/dinner → meal, rehearsal/concert → performance, hotel/check-in → accommodation. |
| Location | Optional. |
| Notes | Optional. Shown under the title. |
A minimal example
Made by hand in Excel or Google Sheets in a couple of minutes: three tabs, these cells.
Sheet "Trip" A B Format tripbinder-export/1 Name 8th Grade DC Trip Destination Washington, DC Departure 2027-04-14 Return 2027-04-16 Sheet "Roster" (first sheet) First name | Last name | Student ID | Grade | DOB | Parent email | Allergies | EC1 name | EC1 phone Ava | Rivera | 100001 | 8 | 2013-04-05 | maria@example.com | Peanuts | Maria Rivera| 610-555-0101 Sheet "Itinerary" Date | Start | End | Title | Location | Notes 2027-04-14 | 07:00 | | Depart school | Bus loop | 2027-04-14 | 12:30 | 13:30 | Lunch | Union Station | Packed lunch 2027-04-14 | | | Free time | Hotel | Until 9 PM
To include a cover photo, add the image file inside the .xlsx (it is a zip) at a path such as xl/media/image1.jpeg and name that path in the Trip sheet’s Cover image row. Libraries that write pictures into worksheets do this for you; a hand-made workbook can simply leave the cover out.
Versioning and privacy
The Format value is tripbinder-export/1. Additions (new optional columns or keys) will not change the number; a breaking change will. A file usually carries health details and family contacts, so treat it like the records it contains: send it over a secure channel and delete it once imported.