Prepare Your Data

In order to write a Template, your data needs to be a CSV file.

Every row is a unique narrative

When Wordsmith produces narratives, any data that is in the same row can be part of the same narrative. Each row generates a separate narrative.


Because of this, you’ll want to prepare your spreadsheet with all the data you want to reference in each narrative. This may mean you need to add some analysis to raw data before using it in Wordsmith, like aggregating fields or adding calculations. And if you have hierarchical data, you'll need to flatten it before using in Wordsmith.

Data Checklist

Before you upload your file, make sure your dataset follows these guidelines:

  • Data file is in a flat CSV file. In general, you can save any single-table spreadsheet as a CSV.
  • Make sure your CSV is encoded in UTF-8 format. If your CSV does not match this format, open the file in Microsoft Notepad and click Save As, then select UTF-8 in the encoding dropdown and save the file. On Apple OS, use Numbers and click Export To ► CSV, then under Advanced Options select Text Encoding: Unicode (UTF-8).
  • Row 1 consists entirely of column headers. Make sure this is the very first row with no spaces or titles above it. All column headers must include at least one letter, so they cannot be all numbers or all kanji, for example. In addition, there are a few column headers that you won't be able to use because it will conflict with our internal database. So make sure you don't use any names from the list below as the column headers in your CSV.
  • Number data uses periods for decimals, not for thousands. You can format your decimals to use either periods or commas in the app, and you can customize your thousands separators to be commas, periods, or spaces. But in order for those to work properly in Wordsmith, you'll need to use periods, not commas, for decimals, and either commas or nothing at all for thousands separators.
  • List data uses commas as delimiters. Other characters like the vertical bar or Japanese comma are not supported as delimiters.
  • Date data is in Month/Day/Year format. Once your dates are passed into Wordsmith, you'll have full control over the formatting and can change it to Day/Month/Year or any other combination, but it does need to originally be in Month/Day/Year format in order for Wordsmith to read it correctly and for the date functions like Get, Ahead, Ago, and Between to work.
  • Limit your CSV to 998 or fewer column headers. Wordsmith can handle datasets with a maximum of 998 columns, so if your raw dataset is larger, be sure to pare it down to only the columns that are important to your narrative.
  • Any aggregation and analysis is done upfront, and is in your CSV before you upload it to Wordsmith. You can do a few simple calculations in Wordsmith using the formulas feature, but ranking, averaging, aggregating, and looking at streaks in your data should be done before you upload your CSV or send data to our API.
  • All rows contain all the data you need for a given narrative. Every row (other than the header row) will become its own narrative.

Do Not Include These Words in the Column Headers in Your CSV

  • and
  • daysago
  • daysahead
  • daysbetween
  • excludes
  • false
  • getday
  • getmonth
  • getweekday
  • getyear
  • id
  • includes
  • monthsago
  • monthsbetween
  • or
  • true
  • yearsago
  • yearsahead
  • yearsbetween