Compiling a residency history into timeline.json

2026-09-04

To draw a timeline of the countries and regions you have lived in, you need data. This post covers gathering scattered records into a single timeline.json file.

1. Start with the skeleton

The top-level structure looks like this.

{
  "birth": "1994-03",
  "expectedAge": 100,
  "places": []
}

birth is your birth year-month. expectedAge is the number of cells to draw in the grid; omit it and the on-screen value or the default of 100 is used. Filling in the places array is the real work.

2. Pull the spans from records

Do not rely on memory — look at the actual paper trail.

Passport — long-stay visa stamps, residence-permit issue and cancellation dates
Government address registry — every domestic move, with dates, is usually on file
Transcripts / enrolment certificates — admission and graduation months
Employment certificates / social-insurance records — start and end dates per employer

Write each span as { "country": ..., "region": ..., "start": ..., "end": ... }. A "YYYY-MM" date is precise enough.

{
  "places": [
    { "country": "South Korea", "region": "Daejeon", "start": "1994-03", "end": "2013-02" },
    { "country": "South Korea", "region": "Seoul",   "start": "2013-03", "end": "2019-08" },
    { "country": "Japan",       "region": "Tokyo",   "start": "2019-09", "end": "2023-04" },
    { "country": "South Korea", "region": "Seoul",   "start": "2023-04" }
  ]
}

The last span’s end is blank, meaning “up to now”.

3. One file for both by-country and by-region

The same file feeds both modes. By-country reads the country value as the color key; by-region reads region. Put both on every entry and one file draws both pictures. If neither is present, the tool falls back to a name field. If you do not need a country split, keep only region, or the other way around.

4. Common mistakes

Gaps between spans — if one span ends 2013-02 and the next starts 2013-05, three months are left blank. If the moving gap was real, leave it; otherwise align the dates.
One-digit months — "2019-9" parses, but "2019-09" everywhere is safer.
The same place under two names — “Seoul” and “Seoul City” become different colors. Fix on one name.

5. Load it and check

Paste the finished JSON into the tool’s input box and press “Visualize”. If colors jump oddly or blank cells do not match what you expect, sections 3 and 4 are usually the cause. You can keep a finished picture by putting it in a URL with “Copy share link”.

More context is in the guide and Exporting your Google Timeline.

← All posts