Notice

This page show a previous version of the article

API

This page describes how to get started with the Tatoeba API.

Retrieving a sentence with a known ID

To retrieve sentence number 1:

https://tatoeba.org/eng/api_v0/sentence/1

Search results

How to Construct a Call Based on an Advanced Search

To figure out how to make a call to the API, you can perform an advanced search from the Tatoeba website, then change the first part of the URL from this:

https://tatoeba.org/en/sentences

to this:

https://tatoeba.org/eng/api_v0

For instance, if you use the advanced search interface to select English sentences without audio that contain the word "those", you will see that the URL looks like this:

https://tatoeba.org/en/sentences/search?from=eng&has_audio=no&native=&orphans=no&query=those&sort=relevance&sort_reverse=&tags=&to=&trans_filter=limit&trans_has_audio=&trans_link=&trans_orphan=&trans_to=&trans_unapproved=&trans_user=&unapproved=no&user=

Change the first part of the URL in order to produce this URL, which uses the API:

https://tatoeba.org/eng/api_v0/search?from=eng&has_audio=no&native=&orphans=no&query=those&sort=relevance&sort_reverse=&tags=&to=&trans_filter=limit&trans_has_audio=&trans_link=&trans_orphan=&trans_to=&trans_unapproved=&trans_user=&unapproved=no&user=

Example 1

Search: English sentences containing the word "play".

Note: The equals sign, represented by "%3D" in the URL, is necessary in order to specify an exact match in English and several other languages. For more information about specifying exact matches, see "Main search field" in How to Search for Text.

query: =play
from: eng

URL: https://tatoeba.org/eng/api_v0/search?from=eng&query=%3Dplay

Example 2

Search: English sentences containing the word "Canadian", "Canadians", etc., that have direct Japanese translations

query: Canadian
from: eng
to: jpn
translations: direct only

URL: https://tatoeba.org/eng/api_v0/search?from=eng&query=Canadian&trans_filter=limit&trans_link=direct&trans_to=jpn&to=jpn

Example 3

Search: English sentences in list 907 containing the word "Boston" that have audio and Japanese translations (direct or indirect), sorted by creation date

query: Boston
from: eng
to: jpn
audio: yes
list: 907
sort: by creation date
translations: direct and indirect

URL: https://tatoeba.org/eng/api_v0/search?from=eng&trans_filter=limit&query=Boston&sort=created&has_audio=yes&list=907&trans_to=jpn&to=jpn

Paging

You can use the count and perPage in the paging information to find out how many pages are contained in the search results. For instance, the following call:

https://dev.tatoeba.org/eng/api_v0/search?from=eng&list=907&query=Canadian&trans_filter=limit&trans_link=direct&trans_to=jpn&to=jpn&page=2

will produce the following result:

"paging": {
  "Sentences": {
    "finder": "all",
    "page": 2,
    "current": 8,
    "count": 18,
    "perPage": 10,
    "start": 11,
    "end": 18,
    "prevPage": true,
    "nextPage": false,
    "pageCount": 2,
    "sort": null,
    "direction": null,
    "limit": null,
    "sortDefault": false,
    "directionDefault": false,
    "scope": null,
    "completeSort": []
}

The relevant properties are:

page: current page
current: number of items displayed in the current page
count: total number of results
perPage: number of results per page

To find the number of pages in total, divide count by perPage and round up to the nearest integer.

GitHub issue

GitHub issue #2669 contains discussion of the API, beginning with the initial proposal.