Version at: 2022/11/20 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
version at: 2022/11/20 20:32
# 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