Edward Betts c6cb06b71e Add car journeys to trips

2026-07-08 09:09:48 +01:00

22 KiB

Raw Blame History

Personal Data YAML Formats

This document describes the YAML files read from ../personal-data/. It is intended for humans and LLMs generating new entries.

General Rules

Use YAML lists for most files. airports.yaml is a mapping keyed by IATA code.
Use ISO-like YAML dates and datetimes:
- Date: 2026-03-14
- Datetime with timezone: 2026-03-14 09:30:00+01:00
Use lowercase ISO 3166-1 alpha-2 country codes, for example gb, be, us.
Use quoted strings for prices and identifiers that might otherwise be parsed as numbers: '154.34', '06525269', '0042'.
Currencies must be in config.CURRENCIES or GBP.
Travel and trip-related entries are grouped by the trip date. That date should match an entry in trips.yaml when a named trip is needed, but trip groups can also be created from travel/accommodation/conference entries.
Keep chronological files sorted by their natural start field. validate_yaml.py checks ordering for trips, flights, trains, ferries, conferences, and accommodation.
Coordinates are latitude then longitude, both numeric.

Cross-File References

flights.yaml flight airline values reference airlines.yaml iata.
flights.yaml flight from and to values reference airports.yaml keys.
trains.yaml journey and leg from and to values reference stations.yaml name.
ferries.yaml from and to values reference ferry_terminals.yaml name.
buses.yaml from and to values reference bus_stops.yaml name.
coaches.yaml from and to values reference coach_stations.yaml name.
car_journeys.yaml route values name files in car_routes/. The .geojson extension is optional.
Station, stop, and terminal routes values name GeoJSON files without the .geojson extension.

`accommodation.yaml`

Top-level shape: list of accommodation stays.

Used by: agenda events, trip pages, trip maps, busy/location logic.

Required fields:

type: accommodation category such as hotel, apartment, airbnb.
name: property name.
country: lowercase country code.
location: city or place name.
trip: trip start date.
from: check-in datetime.
to: check-out datetime.

Common optional fields:

Booking: operator, booking_reference, confirmation_code, booking_url, url, email, phone.
Money: price, currency, room_rate, estimated_taxes, estimated_additional_fees.
Room/stay: address, room_type, room_name, room_number, number_of_adults, breakfast_included, breakfast, cancellation_policy, free_cancellation, refundable.
Coordinates/IDs: latitude, longitude, timezone, osm_node, wikidata.
Loyalty: rewards, radisson_rewards_number.

Example:

- type: hotel
  operator: Example Hotels
  name: Example Central Hotel
  location: Brussels
  country: be
  trip: 2026-02-06
  from: 2026-02-06 15:00:00+01:00
  to: 2026-02-09 11:00:00+01:00
  address: 1 Example Street, Brussels
  confirmation_code: ABC123
  price: '312.50'
  currency: EUR
  number_of_adults: 1
  room_type: Standard double
  breakfast_included: true
  latitude: 50.8466
  longitude: 4.3528

`airlines.yaml`

Top-level shape: list of airlines.

Used by: flight loading and display.

Required fields:

iata: two-character IATA airline code.
icao: three-character ICAO airline code.
name: airline name.

Optional fields:

flight_number_prefer_icao: boolean. When true, display flight numbers with the ICAO code instead of the IATA code.

Example:

- iata: BA
  icao: BAW
  name: British Airways
- iata: U2
  icao: EZY
  name: easyJet
  flight_number_prefer_icao: true

`airports.yaml`

Top-level shape: mapping keyed by IATA airport code.

Used by: flight loading, distance calculation, maps, unbooked route hints.

Required fields for each airport:

iata: IATA code. Should match the mapping key.
name: airport name.
city: city or main served place.
country: lowercase country code.
latitude, longitude: numeric coordinates.
qid: Wikidata QID.

Optional fields:

alt_name: display name override used in labels.
elevation: metres.
website, url.

Example:

BRU:
  iata: BRU
  name: Brussels Airport
  city: Brussels
  country: be
  qid: Q220613
  latitude: 50.9014
  longitude: 4.4844
  elevation: 56
  website: https://www.brusselsairport.be/

`bus_stops.yaml`

Top-level shape: list of bus stops.

Used by: bus trip loading, maps, route rendering.

Required fields:

name: stop name referenced by buses.yaml.
city: city or place.
country: lowercase country code.
latitude, longitude: numeric coordinates.
routes: mapping from destination stop name to GeoJSON filename without .geojson.

Optional fields:

Atco: UK ATCO stop code.
osm_node.

Example:

- name: West Street
  city: Bristol
  country: gb
  Atco: '0100BRA10073'
  osm_node: 485403178
  latitude: 51.4393854
  longitude: -2.6017977
  routes:
    Bristol Airport: West_Street_to_Bristol_Airport

`buses.yaml`

Top-level shape: list of bus journeys.

Used by: trip loading, maps, trip timeline. Bus journeys are not counted for Schengen tracking.

Required fields:

trip: trip start date.
depart: departure datetime.
arrive: arrival datetime. validate_yaml.py requires arrival after departure and duration no more than 12 hours.
from, to: names from bus_stops.yaml.

Optional fields:

operator, price, currency.

Example:

- trip: 2026-03-14
  depart: 2026-03-14 08:20:00+00:00
  arrive: 2026-03-14 08:55:00+00:00
  from: West Street
  to: Bristol Airport
  operator: First Bus
  price: '2.00'
  currency: GBP

`coach_stations.yaml`

Top-level shape: list of coach stations.

Used by: coach trip loading, maps, route rendering.

Fields are the same pattern as bus_stops.yaml, except entries describe coach stations.

Example:

- name: Example Coach Station
  city: Example City
  country: gb
  latitude: 51.4500
  longitude: -2.5800
  routes:
    Other Coach Station: example_city_to_other_city

`coaches.yaml`

Top-level shape: list of coach journeys.

Used by: trip loading, maps, trip timeline. Coach journeys are not counted for Schengen tracking.

Required fields:

trip, depart, arrive, from, to.
from and to must be names from coach_stations.yaml.

Optional fields:

operator, class, booking_reference, price, currency, price_details.

Example:

- booking_reference: ABC123
  trip: 2026-05-25
  price: '55.00'
  currency: GBP
  depart: 2026-05-26 14:45:00+01:00
  arrive: 2026-05-26 18:30:00+01:00
  from: Example Coach Station
  to: Other Coach Station
  operator: Example Coaches
  class: Standard
  price_details:
    base_fare: '55.00'

`car_journeys.yaml`

Top-level shape: list of car journeys.

Used by: trip loading, maps, trip timeline. Car journeys are for driving your own car or a rental car.

Required fields:

trip: trip start date.
depart: departure date or datetime.
arrive: arrival date or datetime.
route: GeoJSON filename in car_routes/, with or without the .geojson extension.

Optional fields:

from, to: endpoint labels. If omitted and the route filename uses A_to_B, labels are inferred from the filename.
from_type, to_type: marker type override. Use home to render a house icon. Otherwise car endpoints render as car markers.
operator, vehicle, price, currency, distance.

The route distance is calculated from the GeoJSON when distance is not present. If an inferred or explicit endpoint label is home, PCH, or Picture House Court, the marker is rendered as a house.

Example:

- trip: 2026-07-16
  depart: 2026-07-16
  arrive: 2026-07-16
  route: PCH_to_EMF.geojson

- trip: 2026-07-16
  depart: 2026-07-19
  arrive: 2026-07-19
  route: EMF_to_PCH.geojson

`conferences.yaml`

Top-level shape: list of conferences and conference-like events.

Used by: agenda events, trip pages, trip maps, conference list, CFP reminders.

Required fields:

name: event name.
topic: topic/category.
location: city or location label.
Date information, either as legacy top-level start and end, or preferred nested dates.

Preferred dates fields:

status: one of exact, tentative, or approximate.
For exact and tentative: start and end dates/datetimes. end must be no earlier than start, and duration must be under 20 days.
For approximate: earliest and latest dates for sorting/past-future filtering.
label: optional human-readable date text. Recommended for tentative and approximate, for example likely first weekend of February 2027 or March 2027.
basis: optional explanation of why a tentative date is expected.

Date status behavior:

exact: confirmed dates. These create agenda events, iCalendar entries, and timeline bars.
tentative: guessed or unconfirmed exact dates. These appear on the conference list with a status badge, but do not create agenda/iCalendar events or timeline bars.
approximate: only a broad date range is known. These appear on the conference list with a status badge, but do not create agenda/iCalendar events or timeline bars.

Legacy fields:

Existing top-level start and end are still supported and are treated as exact unless date_status says otherwise.

Common optional fields:

Series: series, a key from conference_series.yaml.
Trip/location: trip, country, venue, address, latitude, longitude.
Attendance: going, registered, speaking, online, accommodation_booked, transport_booked.
Partial attendance: attend_start, attend_end. These may be dates or timezone-aware datetimes and are used on trip pages instead of official dates.
Web/CFP: url, cfp_end, cfp_url, hashtag, description.
Money/tickets: free, price, currency, ticket_type.
Other flags: hackathon, attendees.

Exact example:

- name: FOSDEM
  series: fosdem
  topic: FOSDEM
  location: Brussels
  country: be
  trip: 2026-02-06
  dates:
    status: exact
    start: 2026-02-07
    end: 2026-02-08
  attend_start: 2026-02-07 14:00:00+01:00
  attend_end: 2026-02-08
  going: true
  registered: true
  accommodation_booked: true
  transport_booked: true
  url: https://fosdem.org/2026/
  venue: Universite Libre de Bruxelles
  address: Av. Franklin Roosevelt 50, 1050 Bruxelles, Belgium
  latitude: 50.8132
  longitude: 4.3822

Tentative example:

- name: FOSDEM
  series: fosdem
  topic: FOSDEM
  location: Brussels
  country: be
  dates:
    status: tentative
    start: 2027-01-30
    end: 2027-01-31
    label: likely first weekend of February 2027
    basis: FOSDEM is usually on the weekend where Sunday is the first Sunday in February
  url: https://fosdem.org/2027/

Approximate examples:

- name: Wikimedia Hackathon 2027
  series: wikimedia-hackathon
  topic: Wikimedia
  location: Albania
  country: al
  dates:
    status: approximate
    label: mid-April 2027
    earliest: 2027-04-11
    latest: 2027-04-20
  hackathon: true

- name: PyCascades 2027
  series: pycascades
  topic: Python
  location: TBC
  dates:
    status: approximate
    label: March 2027
    earliest: 2027-03-01
    latest: 2027-03-31

`conference_series.yaml`

Top-level shape: mapping from stable series ID to series metadata.

Used by: conference list pages, conference series index/detail pages, and validation of conferences.yaml series references.

Required fields for each series:

name: display name for the series.

Common optional fields:

topic: default topic/category.
cadence: for example annual or recurring.
usual_location: common city/place when the event usually stays in one place.
country: common lowercase country code when stable.
url: series homepage.
notes: free-text generation or scheduling notes.

Example:

fosdem:
  name: FOSDEM
  topic: FOSDEM
  cadence: annual
  usual_location: Brussels
  country: be
  url: https://fosdem.org/
  notes: Usually the weekend where Sunday is the first Sunday in February.

geomob-london:
  name: Geomob London
  topic: Maps
  cadence: recurring
  usual_location: London
  country: gb
  url: https://thegeomob.com/

`entities.yaml`

Top-level shape: list of people/entities.

Used by: birthday events.

Required fields for birthday support:

name: full name.
label: display name.
type: for example human.
birthday: mapping with day, month, and optionally year.

Optional fields:

relation, email.

If birthday.year is omitted, age is shown as unknown.

Example:

- name: Ada Example
  label: Ada
  type: human
  relation: friend
  birthday:
    day: 10
    month: 12
    year: 1990

`events.yaml`

Top-level shape: list of general events.

Used by: agenda events and trip pages.

Required fields:

name: event type.
One date source:
- date: single event date/datetime, or
- start_date: used for events with a separate end_date, or
- rrule: recurrence rule string.

Optional fields:

title: display title.
end_date: explicit end date/datetime.
duration: ISO 8601 duration such as PT2H, P1D.
url.
Trip/map fields: trip, location, country, venue, address, latitude, longitude.

Special cases:

For name: travel_insurance, the event date field is end_date; no end_date is attached to the generated event.
For recurring events, if the rrule has no BYHOUR, BYMINUTE, or BYSECOND, generated events are all-day dates. Otherwise generated datetimes are localized to UK time.
skip_trips=True consumers ignore entries with trip.

Examples:

- name: travel_insurance
  start_date: 2026-05-04
  end_date: 2027-05-03

- name: meetup
  title: Example Geo Meetup
  date: 2026-06-18 18:30:00+01:00
  duration: PT2H
  url: https://example.org/meetup
  location: Bristol
  country: gb
  latitude: 51.4545
  longitude: -2.5879

- name: market
  title: Monthly Example Market
  rrule: FREQ=MONTHLY;BYDAY=1SA

`ferries.yaml`

Top-level shape: list of ferry journeys.

Used by: trip loading, maps, trip timeline, Schengen tracking.

Required fields:

trip: trip start date.
depart, arrive: datetimes. Ferry arrive is required.
from, to: names from ferry_terminals.yaml.

Common optional fields:

operator, ferry, direction, class, booking_reference, price, currency.
price_details: free-form mapping of fare components.
vehicle: mapping with fields such as type, registration, height, length, extras.

Example:

- booking_reference: ABC123
  trip: 2026-05-04
  price: '302.00'
  currency: GBP
  depart: 2026-05-04 23:00:00+01:00
  arrive: 2026-05-05 08:00:00+02:00
  from: Portsmouth
  to: Cherbourg
  operator: Brittany Ferries
  class: Commodore cabin
  price_details:
    base_fare: '153.00'
    cabin: '149.00'
  vehicle:
    type: Example car
    registration: AB12CDE
    height: 1.63m
    length: 4.15m

`ferry_terminals.yaml`

Top-level shape: list of ferry terminals.

Used by: ferry loading and route rendering.

Required fields:

name: terminal name referenced by ferries.yaml.
city, country.
latitude, longitude.
routes: mapping from destination terminal name to GeoJSON filename without .geojson. Ferry route rendering expects a GeoJSON route.

Optional fields:

osm_node, osm_way.

Example:

- name: Portsmouth
  city: Portsmouth
  country: gb
  osm_way: 123456
  latitude: 50.8120
  longitude: -1.0880
  routes:
    Cherbourg: portsmouth_cherbourg

`flight_destinations.yaml`

Top-level shape: list of origin rules for unbooked conference flight route hints.

Used by: trip maps when a trip has conferences but no booked travel.

Required fields:

origin: origin airport IATA code.
airline: airline IATA code. Currently loaded for validation/description but not used in origin selection.
destinations: list of destination airport IATA codes.

Example:

- origin: BRS
  airline: U2
  destinations:
    - AMS
    - BCN
    - CDG

`flights.yaml`

Top-level shape: list of flight bookings. Each booking contains one or more flight legs.

Used by: agenda transport events, trip loading, maps, distance calculation.

Required booking fields:

trip: trip start date.
flights: list of flight leg mappings.

Common optional booking fields:

booking_reference, price, currency.

Required flight leg fields:

depart: departure datetime.
from, to: airport IATA codes from airports.yaml.
flight_number: numeric/string flight number without airline prefix.
airline: airline IATA code from airlines.yaml.

Common optional flight leg fields:

Time/location: arrive, from_terminal, to_terminal, duration.
Seat/cabin: seat, seat_type, class, cabin.
Aircraft: plane, registration.
Tracking: distance, co2_kg, openflights_trip, reason.
Ticket/passenger: e_ticket_number, ticket_number, frequent_flyer_number, passenger_name, passengers, baggage, payment_details.

validate_yaml.py checks that every booking has trip, all flight airlines exist in airlines.yaml, bookings are sorted by first departure, and currencies are configured. It reports flights missing co2_kg.

Example:

- booking_reference: ABC123
  trip: 2026-04-22
  price: '62.50'
  currency: GBP
  flights:
    - depart: 2026-04-22 17:20:00+01:00
      arrive: 2026-04-22 20:20:00+02:00
      from: LHR
      to: BRU
      flight_number: '1234'
      airline: BA
      duration: 01:00
      seat: 5F
      seat_type: W
      class: C
      cabin: business
      plane: Airbus A320
      registration: G-ABCD
      co2_kg: 154

`follow_launches.yaml`

Top-level shape: list of SpaceDevs launch slugs.

Used by: no current in-repo reader was found, but the file appears intended as a watch list for launch update tooling.

Example:

- starship-integrated-flight-test-5
- artemis-ii

`stations.yaml`

Top-level shape: list of railway stations.

Used by: train loading, maps, route rendering.

Required fields:

name: station name referenced by trains.yaml.
country: lowercase country code.
latitude, longitude.
routes: mapping from destination station name to GeoJSON filename without .geojson.

Common optional fields:

uic, alpha3, wikidata, osm_node.

Note: the code reads routes, not rotues; rotues appears to be a typo in existing data and should not be used for new entries.

Example:

- name: London St Pancras
  uic: 7015400
  alpha3: STP
  wikidata: Q720102
  latitude: 51.531921
  longitude: -0.126361
  country: gb
  routes:
    Brussels Midi: london_brussels_eurostar

`subscriptions.yaml`

Top-level shape: list of subscriptions.

Used by: subscription renewal agenda events when renewal_date is present.

Required fields:

name: subscription name.

Common optional fields:

Dates: start, start_date, renewal_date.
price: mapping with amount and currency.
term: mapping with duration and unit or term_unit.
Account: email, account_url, account_number.

Only items with renewal_date create agenda events.

Example:

- name: Example Magazine
  start_date: 2026-01-01
  renewal_date: 2027-01-01
  price:
    amount: 99
    currency: GBP
  term:
    duration: 1
    unit: year
  email: me@example.com
  account_url: https://example.com/account
  account_number: '001234'

`trains.yaml`

Top-level shape: list of train journeys. Each journey contains one or more legs.

Used by: agenda transport events, trip loading, trip timeline, maps, stats.

Required journey fields:

operator: booking/operator label.
from, to: station names from stations.yaml.
trip: trip start date.
depart, arrive: journey datetimes or dates.
legs: list of leg mappings.

Common optional journey fields:

class, number, tickets, ticket_code, total_price, co2_kg.

Required leg fields:

from, to: station names from stations.yaml.
depart, arrive.
operator.

Common optional leg fields:

train, number, service, service_number, service_numbers, reporting_number, mode.
Seat/reservation: coach, seat, seat_type, seat_features, reservation_number, platform.
class, trip, url.

Ticket fields are free-form but commonly include booking_reference, url, price, currency, booking_date, ticket, ticket_code, ticket_type, from, to, class, validity, route, fare, quantity, seat_reservation.

Example:

- operator: eurostar
  from: London St Pancras
  to: Brussels Midi
  trip: 2026-02-06
  depart: 2026-02-06 15:04:00+00:00
  arrive: 2026-02-06 18:12:00+01:00
  class: Standard Premier
  tickets:
    - booking_reference: ABCDEF
      url: https://example.com/booking/ABCDEF
      price: '89.00'
      currency: GBP
  legs:
    - from: London St Pancras
      to: Brussels Midi
      depart: 2026-02-06 15:04:00+00:00
      arrive: 2026-02-06 18:12:00+01:00
      coach: 1
      seat: 41
      operator: Eurostar

`travel_rewards.yaml`

Top-level shape: list of travel loyalty accounts.

Used by: no current in-repo reader was found. The file is structured as account metadata.

Common fields:

name: programme name.
type: category such as hotel, airline, rail.
member_number: membership identifier.
balance: current points/miles balance.
expiry: expiry date or null.
url: account URL.
person: account holder key/name.
email, note.

Example:

- name: Example Rewards
  type: hotel
  member_number: '123456789'
  balance: 3665
  expiry: 2027-08-15
  url: https://example.com/rewards
  person: edward

`trips.yaml`

Top-level shape: list of trip metadata.

Used by: trip grouping and trip titles.

Required fields:

trip: trip start date. This is the grouping key used by travel, accommodation, conferences, and trip events.

Optional fields:

name: explicit trip title.
private: boolean. Private trips are hidden from unauthenticated users.

Example:

- trip: 2026-02-06
  name: Brussels for FOSDEM
  private: false

22 KiB Raw Blame History

Personal Data YAML Formats

General Rules

Cross-File References

accommodation.yaml

airlines.yaml

airports.yaml

bus_stops.yaml

buses.yaml

coach_stations.yaml

coaches.yaml

car_journeys.yaml

conferences.yaml

conference_series.yaml

entities.yaml

events.yaml

ferries.yaml

ferry_terminals.yaml

flight_destinations.yaml

flights.yaml

follow_launches.yaml

stations.yaml

subscriptions.yaml

trains.yaml

travel_rewards.yaml

trips.yaml

22 KiB

Raw Blame History

`accommodation.yaml`

`airlines.yaml`

`airports.yaml`

`bus_stops.yaml`

`buses.yaml`

`coach_stations.yaml`

`coaches.yaml`

`car_journeys.yaml`

`conferences.yaml`

`conference_series.yaml`

`entities.yaml`

`events.yaml`

`ferries.yaml`

`ferry_terminals.yaml`

`flight_destinations.yaml`

`flights.yaml`

`follow_launches.yaml`

`stations.yaml`

`subscriptions.yaml`

`trains.yaml`

`travel_rewards.yaml`

`trips.yaml`