# Example Sentences API
> Real example sentences with human translations as an API — powered by Tatoeba, the large collaborative corpus of millions of sentences in hundreds of languages, each linked to translations contributed and reviewed by real people (not machine translation). Search for sentences containing a word or phrase in one language and get how they are actually translated into another — perfect for seeing a word "in the wild", building vocabulary and flashcards, or as a human-quality translation aid. Look up any sentence by id to get its full set of translations. From "good morning" in English to its German, French, Spanish, Japanese or Mandarin equivalents, across ISO-639-3 languages, it is ideal for language-learning, vocabulary, flashcard, dictionary-companion and linguistics applications. A human-translated example-sentence corpus — distinct from dictionaries (definitions), machine translation and word APIs. Open data from Tatoeba (CC-BY 2.0 FR / CC0).

## Authentication
All requests require your oanor API key in the `x-oanor-key` header. Get one at https://www.oanor.com/developer/keys.

```bash
curl -H "x-oanor-key: oanor_live_…" "https://api.oanor.com/tatoeba-api/..."
```

## Pricing
- **Free** (Free) — 3,100 calls/Mo, 2 req/s
- **Starter** ($8/Mo) — 64,000 calls/Mo, 8 req/s
- **Pro** ($24/Mo) — 300,000 calls/Mo, 20 req/s
- **Mega** ($64/Mo) — 1,050,000 calls/Mo, 50 req/s

## Endpoints

### Sentences

#### `GET /v1/search` — Example sentences with translations

**Parameters:**
- `q` (query, optional, string) — Word or phrase to search Example: `good morning`
- `from` (query, optional, string) — Source language (ISO-639-3), e.g. eng Example: `eng`
- `to` (query, optional, string) — Translation language (ISO-639-3), e.g. deu Example: `deu`
- `limit` (query, optional, string) — Max results (1-50, default 10)

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/tatoeba-api/v1/search?q=good+morning&from=eng&to=deu"
```

**Response:**
```json
{
    "data": {
        "to": "deu",
        "from": "eng",
        "count": 10,
        "query": "good morning",
        "total": 105,
        "sentences": [
            {
                "id": 2258234,
                "lang": "eng",
                "text": "Good morning.",
                "lang_name": "English",
                "translations": [
                    {
                        "id": 382123,
                        "lang": "deu",
                        "text": "Guten Morgen!",
                        "lang_name": "German"
                    },
                    {
                        "id": 4325231,
                        "lang": "deu",
                        "text": "Guten Morgen.",
                        "lang_name": "German"
                    },
                    {
                        "id": 380701,
                        "lang": "deu",
                        "text": "Hallo!",
                        "lang_name": "German"
                    },
                    {
                        "id": 659813,
                        "lang": "deu",
                        "text": "Grüß Gott!",
                        "lang_name": "German"
                    },
                    {
                        "id": 676082,
                        "lang": "deu",
                        "text": "Guten Tag!",
                        "lang_name": "German"
                    },
                    {
                        "id": 3631301,
              
…(truncated, see openapi.json for full schema)
```

#### `GET /v1/sentence` — A sentence + its translations

**Parameters:**
- `id` (query, optional, string) — A Tatoeba sentence id (from /v1/search) Example: `2258234`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/tatoeba-api/v1/sentence?id=2258234"
```

**Response:**
```json
{
    "data": {
        "sentence": {
            "id": 2258234,
            "lang": "eng",
            "text": "Good morning.",
            "license": "CC BY 2.0 FR",
            "lang_name": "English",
            "based_on_id": 0,
            "translations": [
                {
                    "id": 2481703,
                    "lang": "abk",
                    "text": "Шьыжьбзиа!",
                    "lang_name": "Abkhaz"
                },
                {
                    "id": 849446,
                    "lang": "afr",
                    "text": "Goeie môre.",
                    "lang_name": "Afrikaans"
                },
                {
                    "id": 6983687,
                    "lang": "akl",
                    "text": "Mayad nga agahon.",
                    "lang_name": "Aklanon"
                },
                {
                    "id": 13192426,
                    "lang": "amh",
                    "text": "Endemin aderk /እንደ ምን አደርክ/",
                    "lang_name": "Amharic"
                },
                {
                    "id": 7482088,
                    "lang": "ara",
                    "text": "صباح الخير",
                    "lang_name": "Arabic"
                },
                {
                    "id": 7830602,
                    "lang": "arg",
                    "text": "Buen diya.",
                    "lang_name": "Aragonese"
                },
                {
  
…(truncated, see openapi.json for full schema)
```

### Meta

#### `GET /v1/meta` — Endpoint catalogue, languages & notes

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/tatoeba-api/v1/meta"
```

**Response:**
```json
{
    "data": {
        "note": "Tatoeba is a large, community-built corpus of example sentences in hundreds of languages, each linked to human-contributed translations (not machine translation). /v1/search?q=good morning&from=eng&to=deu = find example sentences containing a word or phrase in the 'from' language and get their translations, optionally restricted to a 'to' language — each result has the sentence id, language, text and a list of translations (language + text); omit from/to to search across all languages. /v1/sentence?id=2258234 = a single sentence with its id, language, text, license and all its translations. Language codes are ISO 639-3 (eng, deu, fra, spa, jpn, cmn, …; see common_languages). Data from Tatoeba (CC-BY 2.0 FR / CC0). A human-translated example-sentence corpus — distinct from dictionaries (definitions), machine translation and word APIs. Ideal for language-learning, vocabulary, flashcard, translation-aid and linguistics tools.",
        "source": "Tatoeba — collaborative example-sentence corpus (tatoeba.org)",
        "endpoints": [
            "/v1/search",
            "/v1/sentence",
            "/v1/meta"
        ],
        "common_languages": {
            "ara": "Arabic",
            "cmn": "Mandarin Chinese",
            "deu": "German",
            "ell": "Greek",
            "eng": "English",
            "fra": "French",
            "ita": "Italian",
            "jpn": "Japanese",
            "kor": "Korean",
            "nld": "Du
…(truncated, see openapi.json for full schema)
```


---
Marketplace page: https://www.oanor.com/api/tatoeba-api
OpenAPI spec: https://www.oanor.com/api/tatoeba-api/openapi.json