Version at: 16/6/21 0:47
# API
Briefly, ...
## For one sentence
https://tatoeba.org/eng/api_v0/sentence/1
## Search results
### Search: Canadian (not an exact match, so gets "Canadians", too.)
from: eng
to: jpn
list: 907
direct translations 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: created
(direct and indirect translations)
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
direct translations 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
Do an advanced search, copy the resulting URL and change the first part of the URL to match the first part of the API URL.
https://tatoeba.org/en/sentences/advanced_search
## Paging
You can find out how many pages there thanks to the count and the perPage in the paging information.
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
"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 properties you'll be interested in are:
page - this is the current page.
current - this is the number of items displayed in the current page.
count - this is the total number of results.
perPage - this is the number of results per page.
To know how many pages there are in total, you divide count by perPage and round up to the upper integer.
## For information on the API, ...
See https://github.com/Tatoeba/tatoeba2/issues/2669
version at: 20/11/22 20:31
# 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][1].
[1]: https://github.com/Tatoeba/tatoeba2/issues/2669