Import guide

Bring your
spreadsheet along.

Years of “who did I see today” in Google Sheets, Excel, Numbers or another app? Turn it into a Friends Orbit backup, then import it in the app. Every layout is different, so we let an AI do the fiddly part, with rules that make it ask you instead of guessing.

  1. 1

    Pick a way

    Let the AI convert your file, or write a script you run yourself.

  2. 2

    Answer its questions

    Is “Sam” the same person as “Sammy”? Who’s in “the Millers”? You decide.

  3. 3

    Get the zip

    “Orbit backup 2026-11-17.zip”, with three plain CSV files inside.

  4. 4

    Import it

    In Friends Orbit: Settings → Import your data…, and pick the zip.

Two ways.
Your call.

Easiest

Let the AI convert it

Attach your spreadsheet to ChatGPT, Claude or another assistant that can read files, and paste the prompt. It asks about anything unclear, shows a summary, and hands you the zip.

Your file goes to that AI company. Friends Orbit never sees it, but the assistant does. Check its settings first: turn off “use my chats for training”, or use a temporary chat.

Most private

Let the AI write a script

Share only your column headers and two made-up rows. The AI writes a small Python script; you run it on your computer, and it builds the zip there.

No real name leaves your computer. Needs Python 3, which is free; the AI explains how to install and run it.

Way 1

Convert with ChatGPT or Claude

  1. Open a new chat in ChatGPT, Claude or another assistant that can read and create files.
  2. Attach your spreadsheet. From Google Sheets: File → Download → Microsoft Excel (.xlsx) or CSV.
  3. If you’ve imported before, attach that backup’s people.csv too, so people keep their ids.
  4. Copy the prompt, paste it, send.
  5. Answer the questions, check the summary, download the zip.
Prompt: convert my file
I keep track of who I meet each day, and I'm moving to Friends Orbit, a phone app for iPhone and Android. I've attached my data (a spreadsheet, a CSV, or an export from another app). Please convert it into a Friends Orbit backup file that the app can import.

## The format

One .zip file named "Orbit backup YYYY-MM-DD.zip" (today's date) holding three files at the top level: people.csv, meetings.csv and days.csv. Each is UTF-8, comma-separated, with a header row; a field that contains a comma, a quote or a line break is wrapped in double quotes, with quotes inside doubled.

### people.csv
One row per person.
- `person_id` (required): A stable, unique id: lowercase letters a–z, digits and hyphens, e.g. anna, anna-k, jo-2. Never the same id for two people.
- `display_name` (required): The name as written, keeping accents and umlauts exactly.
- `circles` (optional): Groups the person is in (family, work, a sport, where you met), several joined by "|", e.g. Family|Climbing.
- `notes` (optional): Free text about the person.

### meetings.csv
One row per person per day you met.
- `date` (required): The day, as YYYY-MM-DD.
- `person_id` (required): Someone from people.csv.
- At most one row per person and day.

### days.csv
One row per day you logged.
- `date` (required): The day, as YYYY-MM-DD.
- `comment` (optional): A note for the day.
- `met_nobody` (optional): 1 if the day was logged on purpose with nobody, otherwise 0.
- Leave out days that were never logged: they stay empty in the app.

A tiny example:

people.csv
```
person_id,display_name,circles,notes
anna,Anna,Climbing,
jo,Jo,Family|Neighbours,Lives next door
anna-k,Anna,Work,Desk opposite
```

meetings.csv
```
date,person_id
2026-03-07,anna
2026-03-07,jo
2026-03-09,anna-k
```

days.csv
```
date,comment,met_nobody
2026-03-07,"Bouldering, then dinner",0
2026-03-08,,1
2026-03-09,,0
```

## Rules

1. Never invent data. Everything in the files must come from my data.
2. Don't merge people on your own. If two spellings could be the same person (nicknames, typos, with or without a surname, initials), list them and ask me. Two names on the same day are always two different people.
3. Two different people with the same name each get their own person_id, but keep the display_name as written. Put what tells them apart (where we met, a group) into circles: the app uses circles to tell people with the same name apart.
4. If an entry stands for several people (a couple, a family, "the team"), ask me who is in it and log each member separately.
5. Work out the date format. If there's a weekday column, check the dates against it. If the year is missing or a date is ambiguous (01/02/2026 could be 1 February or 2 January), ask me.
6. If an entry isn't a person (a place, an event, "work"), ask me whether to drop it or move it into that day's comment.
7. Ignore columns that don't fit the format (mood, hours, ratings and so on), and tell me which ones you ignored.
8. If I give you a people.csv from an earlier import, reuse its person_id for everyone already in it, so the app doesn't create duplicates.

## How to work

1. Read my data and tell me briefly what you found: the columns, the date range, and how names are written.
2. Ask all your questions (rules 2 to 6) in one list, numbered, so I can answer by number. Wait for my answers.
3. Show a summary: number of days, people and meetings, the date range, and the 20 people I met on the most days. Wait for my OK.
4. Create the zip and give it to me as a download. If you can't create files, give me the three CSV files as separate code blocks instead.
5. End with: "In Friends Orbit, open Settings → Import your data… and pick this file." Importing only adds what's missing, so importing the same file twice is safe.

For Claude users

Or install it as a Claude skill

The same instructions as a skill, so you only have to say “convert this for Friends Orbit” next time. In Claude, open Settings → Capabilities → Skills, choose Upload skill, and pick the zip. In Claude Code, put the folder into ~/.claude/skills/.

Way 2

A script that runs on your computer

  1. Copy the prompt into any AI chat. Don’t attach your file.
  2. Replace the placeholder with your header row and two rows you make up, e.g. Date,Day,People and 03.01.2026,Sat,"Sam, Lou".
  3. Save the script it writes next to your exported CSV and run it, as the AI explains.
  4. It lists names that look alike. Put the ones that are the same person into aliases.csv and run it again.
Prompt: write me a converter
I keep track of who I meet each day, and I'm moving to Friends Orbit, a phone app for iPhone and Android. My data contains names of real people, so I won't share it with you. Instead, please write me a script that I run on my own computer to convert it.

Here are my column headers and two made-up example rows in the same layout as my real file:

[PASTE YOUR HEADER ROW AND TWO MADE-UP ROWS HERE]

My file is a: [CSV / Excel .xlsx / Numbers / other — say which]

Write one Python 3 script that uses only the standard library (if my file is Excel or Numbers, tell me how to export it as CSV first). It reads my file and writes the Friends Orbit backup zip described below, next to the input file.

## The format

One .zip file named "Orbit backup YYYY-MM-DD.zip" (today's date) holding three files at the top level: people.csv, meetings.csv and days.csv. Each is UTF-8, comma-separated, with a header row; a field that contains a comma, a quote or a line break is wrapped in double quotes, with quotes inside doubled.

### people.csv
One row per person.
- `person_id` (required): A stable, unique id: lowercase letters a–z, digits and hyphens, e.g. anna, anna-k, jo-2. Never the same id for two people.
- `display_name` (required): The name as written, keeping accents and umlauts exactly.
- `circles` (optional): Groups the person is in (family, work, a sport, where you met), several joined by "|", e.g. Family|Climbing.
- `notes` (optional): Free text about the person.

### meetings.csv
One row per person per day you met.
- `date` (required): The day, as YYYY-MM-DD.
- `person_id` (required): Someone from people.csv.
- At most one row per person and day.

### days.csv
One row per day you logged.
- `date` (required): The day, as YYYY-MM-DD.
- `comment` (optional): A note for the day.
- `met_nobody` (optional): 1 if the day was logged on purpose with nobody, otherwise 0.
- Leave out days that were never logged: they stay empty in the app.

A tiny example:

people.csv
```
person_id,display_name,circles,notes
anna,Anna,Climbing,
jo,Jo,Family|Neighbours,Lives next door
anna-k,Anna,Work,Desk opposite
```

meetings.csv
```
date,person_id
2026-03-07,anna
2026-03-07,jo
2026-03-09,anna-k
```

days.csv
```
date,comment,met_nobody
2026-03-07,"Bouldering, then dinner",0
2026-03-08,,1
2026-03-09,,0
```

What the script must do:

1. Never merge people on its own. Read an optional aliases.csv (columns raw_name, person_id) where I map spellings to one person; every name not in it gets its own person_id made from the name.
2. Print the names that look alike (same letters ignoring case and accents, or one is the start of the other), so I can decide which belong together and add them to aliases.csv.
3. Read an optional previous people.csv and reuse its person_ids.
4. Check dates against a weekday column if there is one, and stop with a clear message on a date it can't read.
5. Print a summary at the end: days, people, meetings, date range, and the 20 people met on the most days.

Then explain in a few short steps how I run it on a Mac or Windows PC. Finally, remind me: in Friends Orbit, open Settings → Import your data… and pick the zip.

Then, in the app.

  1. Save the zip somewhere your phone can reach: iCloud Drive or Files on iPhone, Google Drive or Downloads on Android, or send it over with AirDrop or Quick Share.
  2. Open Friends Orbit. On the first screen tap Import your data…, or later go to Settings → Import your data…
  3. Pick the zip. The app tells you how many people, meetings and days it added.

An import only adds what’s missing. Nothing you changed in the app is overwritten, so importing the same file twice, or adding an older year later, is safe.

Reference

The format

Prefer doing it by hand? A backup is one .zip with three CSV files: UTF-8, comma-separated, with a header row. Dates are always YYYY-MM-DD. The app’s own backups use exactly this format, so you can open one to see it.

people.csv

One row per person.

ColumnContent
person_idrequiredA stable, unique id: lowercase letters a–z, digits and hyphens, e.g. anna, anna-k, jo-2. Never the same id for two people.
display_namerequiredThe name as written, keeping accents and umlauts exactly.
circlesGroups the person is in (family, work, a sport, where you met), several joined by "|", e.g. Family|Climbing.
notesFree text about the person.

meetings.csv

One row per person per day you met.

ColumnContent
daterequiredThe day, as YYYY-MM-DD.
person_idrequiredSomeone from people.csv.

At most one row per person and day.

days.csv

One row per day you logged.

ColumnContent
daterequiredThe day, as YYYY-MM-DD.
commentA note for the day.
met_nobody1 if the day was logged on purpose with nobody, otherwise 0.

Leave out days that were never logged: they stay empty in the app.

Download an example backup

Six made-up people over two weeks. You can import it to try the app.