Notice

This page show a previous version of the article

API

This page gives a few examples of how to use the Tatoeba API.

For one sentence

To retrieve sentence number 1:

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

Search results

Search: "Canadian" (not an exact match, so also matches "Canadians")

from: eng to: jpn list: 907 translations: direct only

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

Search: "Boston"

from: eng to: jpn audio: yes sort: by creation date translations: direct and indirect

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

Search: "=play" (exact match)

from: eng to: jpn list: 907 sort: words translations: direct only

https://tatoeba.org/eng/api_v0/search?from=eng&list=907&query=%3Dplay&sort=created&trans_filter=limit&trans_link=direct&trans_to=jpn&to=jpn

Other

To figure out how to make a call to the API, perform an advanced search, 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 that can be called against 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=

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.

For more information on the API

See Tatoeba/tatoeba2 GitHub issue #2669.