Version at: 2023/10/07 00:09
# 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](text-search#)._
- 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][1] contains discussion of the API, beginning with the initial proposal.
* [https://github.com/Tatoeba/tatoeba2/issues/2669](https://github.com/Tatoeba/tatoeba2/issues/2669)
## Also read ....
* [Using the Tatoeba Corpus for Your Own Projects](https://en.wiki.tatoeba.org/articles/show/using-the-tatoeba-corpus)
version at: 2023/10/07 03:20
# 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](text-search#)._
- 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][1] contains discussion of the API, beginning with the initial proposal.
* [https://github.com/Tatoeba/tatoeba2/issues/2669](https://github.com/Tatoeba/tatoeba2/issues/2669)
## Also read ....
* [Using the Tatoeba Corpus for Your Own Projects](https://en.wiki.tatoeba.org/articles/show/using-the-tatoeba-corpus)
* [api.dev.tatoeba.org](https://api.dev.tatoeba.org/)