Version at: 22/11/22 02.11
# 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 "Canadian" that have direct Japanese translations
_Note that in English, unless the search string is preceded by an equals sign, the search will not be exact, so this query will also match "Canadians". For for more information, see "Main search field" in [How to Search for Text](text-search#)._
- 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 2
Search: English sentences containing the word "Boston" that have audio and Japanese translations (direct or indirect), sorted by creation date
- from: **eng**
- to: **jpn**
- audio: **yes**
- 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&trans_to=jpn&to=jpn`
### Example 3
Search: English sentences containing the word "=play" (exact match) in list 907 that have direct translations in Japanese
- from: **eng**
- to: **jpn**
- list: **907**
- sort: **words**
- translations: **direct only**
URL:
`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`
## 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: 22/11/22 02.22
# 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", where the equals sign (represented by "%3D" in the URL) is necessary in order to specify an exact match. _(For more information about specifying exact matches, see "Main search field" in [How to Search for Text](text-search#).)_
- from: **eng**
- sort: **words**
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
- 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
- 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.
## For more information on the API
See Tatoeba/tatoeba2 GitHub issue [#2669][1].
[1]: https://github.com/Tatoeba/tatoeba2/issues/2669