Rules for formatting imported text files

Despite widespread adoption, unfortunately, there is no single standard that defines how a CSV file should be created. We have tried to adopt the most universal standard used, and for the most part, if you create your CSV files using popular spreadsheet applications such as Microsoft Excel, Open Office, or Apple Numbers, you should be able to import the files without too much difficulty.

For data sourced from other locations, you may need to modify data from some applications in a text editor before importing to ensure it conforms with the following rules.

Supported files

We support importing any of the following files:

  • Comma-separated values (CSV) files with ASCII or UTF-8 encoding (see below)
  • Tab-separated values (TSV) files with ASCII or UTF-8 encoding (see below)

Imported files must have one of the following file extensions:

  • csv
  • tsv
  • txt

Internal file rules

In order to import data from a CSV file, the file must conform to the following rules: 
  1. The file can include a single header line of text that provides a label for each column. 
    • This is optional, but recommended, as it will make it easier to configure import settings.
    • This line must observe the same rules as listed below for data lines
  2. One record is entered per line.
    • Newlines within a record are allowed, provided the field is surrounded by straight double quotes (see below).
  3. The fields within each record must be delimited with either commas or tabs.
    • You must be consistent with this choice throughout the file. Do not switch between commas and tabs, as only one will be recognised.
  4. Each record should contain the same number of fields/delimiters.
    • It is acceptable to leave some fields empty, but their delimiters should remain intact.
  5. Any field values that include delimiters (comma or tab, depending on what is used) or new lines must be included in straight double quotes ("). 
    • It is best practice, but not required, to enclose all fields with these quotes
    • Curly quotes must not be used when surrounding values.
  6. Any double quotes within field values must be escaped by placing a second double quote next to the first. For example, the text value: 
    She said "It's me!"
    Would need to be written as: 
    "She said ""It's me!""

Multi-value columns

Some columns within your file may contain multiple values within a single record: an event may have several "tags" listed within the one column.
In such instances, the field must be surrounded by double quotes, and each separate value inside the field should be separated by a comma.

Converting to UTF-8 format

If your timeline file is not already in UTF-8 format, you will need to convert it to UTF-8 format before you can import it. 

Mac OS X

On Mac, you should be able to open your csv file with TextEdit and convert it as follows: 
  1. Hold down the Alt key and click on the File menu.
  2. Choose Save As…
  3. In the save dialog, change the Plain Text Encoding dropdown, choose Unicode (UTF-8).

Windows

On Windows, many tools are available to convert to UTF-8 format. You can download a text editor such as  Notepad++ and open the file. 
Using Notepad++, you can do the following: 
  1. Open the file in Notepad++.
  2. Click on the Encoding menu, and choose your current file encoding by choosing Encode in XXX.
  3. Open the Encoding menu again, and choose Convert to UTF-8.
  4. Save the file (you can use Save As and change the file name if you wish).