An open dataset of Turkish coffee cup reading symbols (and why the part of the cup matters)

onder yazici — Thu, 29 Oct 2026 20:30:55 +0000

Turkish coffee leaves a thick layer of grounds in the cup. Turn the cup over onto its saucer, let it cool, and the grounds dry into shapes: a bird, a snake, a ring. Reading those shapes (kahve falı, a form of tasseography) is a living tradition in Türkiye, Greece and much of the Middle East.

When I looked for a structured list of the symbols, there wasn't one. Not on GitHub, not on Hugging Face, not on Kaggle (as of October 2026). There are plenty of web pages, but they repeat the same one-line meanings, and almost none of them say where in the cup a shape sits, which in practice is half of the reading.

So I published one.

What's in it

40 symbols, each in Turkish and English:

the name and a category (animals, shapes, objects, people, nature)
what folk tradition says about it, in a few words
a calmer reading that avoids fear and prediction (no "an enemy is near", no "money is coming")
a short gist for each of the five parts of the cup: the rim, the side, the bottom, near the handle, and the saucer
a link to the full page for the symbol

One record:

{
  "id": "yilan",
  "name_tr": "Yılan",
  "name_en": "Snake",
  "category": "animals",
  "traditional_en": "a rival posing as a friend",
  "falyora_reading_en": "something moving by winding rather than straight",
  "zones": {
    "rim": "a roundabout matter in the near term",
    "side": "an ongoing process not going straight",
    "bottom": "a matter carried for a long time",
    "handle": "your own hesitation or indirect path",
    "saucer": "a general situation from outside"
  },
  "url_en": "https://falyora.app/en/symbols/snake"
}

(The Turkish fields are left out above to keep it short.)

Why the zones

In the tradition, the same shape means different things in different places. Near the rim it's about now; on the bottom it's about something older, or further away; near the handle it's about you; on the saucer it's about the people around you. A list of "snake = enemy" throws that away. Keeping the five zones as separate fields is the main thing this dataset adds.

How it was made

The symbols come from the dictionary on falyora.app. Those pages are written with the help of AI tools and checked twice before they go live: a program scans for fear language, health hints, exact dates and pages that read too much alike, and sensitive pages are read again (editorial policy).

The dataset is not a copy of those pages. Each field is a short summary written for the dataset, and a small validator (build.py, MIT) checks:

every id has a Turkish and an English page, and names and categories match
each field stays within a word limit
no run of eight or more words is copied from the page text
no banned words (enemy, betrayal, curse, illness, exact dates)

Using it

import json, urllib.request

url = "https://falyora.app/open-data/coffee-cup-symbols/symbols.json"
symbols = json.load(urllib.request.urlopen(url))
for s in symbols:
    print(s["name_en"], "-", s["zones"]["handle"])

Some ideas:

a symbol picker or glossary for a tasseography project
teaching material about Turkish coffee culture
labels for research on shapes in coffee cup photos

Get it

Page: https://falyora.app/en/open-data
GitHub: https://github.com/0xBusuzima/coffee-cup-symbols
JSON: https://falyora.app/open-data/coffee-cup-symbols/symbols.json
CSV: https://falyora.app/open-data/coffee-cup-symbols/symbols.csv
License: data CC BY 4.0 (credit "Falyora (falyora.app)"), code MIT. CITATION.cff is included.

About the app

I made the dataset alongside Falyora, an Android app that reads coffee cups from photos with AI and says so openly. It marks the shapes it found on the photo so you can check them yourself. Readings are for entertainment. The dataset doesn't depend on the app; the app is just why I needed it.

If you spot a mistake in the data, or know a regional reading that's missing, I'd like to hear it.

DEV Community: onder yazici