CSV mapping reference
The advanced importer maps source column names to destination fields. The source column name is whatever appears in the first row of your file.
Standard book fields
| Destination | Examples of source columns | Notes |
|---|---|---|
| Title | Title, Book Title, Name |
Required unless an ISBN can supply the title |
| Author | Author, Authors, Writer |
Primary contributor |
| Additional authors | Additional Authors, Co-authors |
Comma-separated contributors are supported |
| ISBN | ISBN, ISBN10, ISBN13, ISBN/UID |
Keep as text; hyphens are accepted |
| Publisher | Publisher |
Shared book metadata |
| Published date/year | Published Date, Year Published |
Dates are normalized where possible |
| Page count | Pages, Number of Pages |
Numeric value |
| Language | Language |
Defaults to English when not provided |
| Cover URL | Cover URL |
Existing URL can be retained or replaced manually |
| Series | Series, Series Volume, Series Order |
Used for series relationships |
| Categories | Categories, Genres |
Shared categories; source tags may be better as personal fields |
| Media type | Format, Media Type |
Physical book, e-book, audiobook, or Kindle |
| Rating data | Average Rating, Rating Count |
Community/provider data |
Personal reading fields
| Destination | Examples of source columns | Notes |
|---|---|---|
| Reading status | Exclusive Shelf, Read Status, Status |
Can be supplemented by the default status setting |
| My rating | My Rating, Star Rating |
Personal rating |
| Date added | Date Added |
Personal library date |
| Start/finish date | Date Started, Date Read, Date Finished |
Personal reading history |
| Notes/review | My Review, Review, Private Notes |
Keep private content in personal fields |
| Tags/shelves | Bookshelves, Tags |
Personal organization data |
| Location | Location |
Links the book to a configured location |
Global versus personal custom fields
Choose Global for information that should describe the shared book record, such as binding or provider data. Choose Personal for your shelves, moods, content warnings, or private classifications.
Available field types include text, number, date, boolean, rating, tags, URL, email, and long text. A field created during import is available for later editing from the metadata settings.
Example custom file
Title,Author,ISBN,My Rating,Read Status,Date Read,Personal Shelf
The Left Hand of Darkness,Ursula K. Le Guin,9780441478125,5,read,2025-04-12,Classic SF
Map Personal Shelf to a personal custom field. If the ISBN is absent, the title can still import and will appear in Needs Review.
Common source formats
Goodreads and StoryGraph exports have default mappings. Review them before starting because export columns can change over time. For a new source format, map a small sample, save the mapping as a template, and reuse it for future exports.
Import hygiene
- Use one header row.
- Use UTF-8.
- Keep ISBNs as text.
- Avoid duplicate headers.
- Prefer ISO dates.
- Do not map a private review to a global field.
- Keep the original export so an error report can be reconciled with source row numbers.