Public API

What it offers

The public API lives at https://api.eipane.com/. It is read-only: it returns entries, search results, a random entry, the phrase of the day, themes, collections and the personal names that appear in sayings. No sign-up is needed.

Every response includes an attribution object with the source (eipane.com), a link to the canonical page and the licence (CC BY 4.0). Each entry also carries its url on eipane.com.

The content is the Greek archive: titles, meanings, background, examples and labels are returned in Greek. The English editions on these pages are not part of the API.

The machine-readable description is at https://api.eipane.com/openapi.json.

Endpoints

All endpoints use GET and return application/json. CORS is open (Access-Control-Allow-Origin: *), so you can call them from a browser.

GET /

API index: name, version, links to every endpoint, rate limits and attribution.

GET /openapi.json

The OpenAPI document (machine-readable description of every endpoint and parameter).

GET /v1/entries

List public entries. Filters: type, theme, collection, name, indexable; paging: page (from 1), per_page (1–100, default 20).

GET /v1/entries/{slug}

One entry by its slug, the same slug as its page on eipane.com.

GET /v1/search?q=

Search, accent-insensitive and Greeklish-aware. q needs at least two characters. Same filters and paging as /v1/entries.

GET /v1/random

A random public entry. Optional type and indexable.

GET /v1/today

The phrase of the day, fixed for each calendar date in the Europe/Athens time zone. Optional type and indexable.

GET /v1/themes

The themes (topics), each with its entry count and page URL.

GET /v1/collections

The collections, each with its entry count and page URL.

GET /v1/names

Personal names that appear in sayings (Yiannis, Maria and others).

GET /v1/names/{slug}

One personal name and the entries that use it.

type is one of gnomiko (saying or quotation), paroimia (proverb), ekfrasi (expression or idiom) or lexi (word). indexable=true returns only reviewed entries that eipane lists for search engines; indexable=false returns only published entries still awaiting review. List responses include page, per_page, total and pages; /v1/entries also returns links.next and links.prev.

Errors are JSON as well, for example 404 with {"error":{"code":"not_found",…}} for an unknown slug, or 400 with bad_query when q is shorter than two characters.

Examples

Search works with Greek, with or without accents, and with Greeklish, just like the site. Encode non-Latin text in the URL (curl does it for you with -G and --data-urlencode):

curl "https://api.eipane.com/v1/search?q=kallio%20arga"

curl -G "https://api.eipane.com/v1/search" --data-urlencode "q=καλός"

One entry:

curl https://api.eipane.com/v1/entries/kallio-arga-para-pote

Only reviewed, indexable proverbs, five per page:

curl "https://api.eipane.com/v1/entries?type=paroimia&indexable=true&per_page=5"

The phrase of the day, or only indexable entries (as the widgets use):

curl https://api.eipane.com/v1/today

curl "https://api.eipane.com/v1/today?indexable=true"

A random idiom:

curl "https://api.eipane.com/v1/random?type=ekfrasi&indexable=true"

Names in the sayings, for example Yiannis:

curl https://api.eipane.com/v1/names

curl https://api.eipane.com/v1/names/giannis

Licence and attribution

The original explanations and editorial notes are covered by the content licence (CC BY 4.0). Wherever a result quotes or reproduces entries, credit eipane.com with a link, ideally to the entry’s own url. Third-party quotations and the eipan name and logo are excluded from the licence. Use of the API is subject to the terms of use (in Greek).

Rate limits

Without a key, each IP address may make 60 requests per minute; responses carry a RateLimit-Limit header. A higher limit with an API key is planned, but keys are not being issued yet. Please do not try to get around the limits.

Widgets

If you just want to show a Greek phrase on your website, the ready-made widgets (phrase of the day, random phrase and a “what does it mean?” lookup) call the API from your visitors’ browsers and show the required credit to eipane.com.